fix(agent): clean up alias follow-up findings

[cv]

Summary

Follow-up to #5881 that addresses automated review feedback after the Deep Agents alias PR merged.
It removes an unused alias import and expands installer/TypeScript alias parity coverage so every exported alias key is checked.

Changes

• Removed the unused agentAliasSummary named import from src/lib/agent/defs.ts.
• Changed test/install-agent-alias-parity.test.ts to derive parity cases from exported AGENT_ALIASES rather than a hand-picked subset.
• Kept normalization-only cases for uppercase, underscore, and spaced alias inputs.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: follow-up only changes an unused import and test coverage.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only)
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

Verification commands run:

• npm run build:cli
• npx vitest run test/install-agent-alias-parity.test.ts src/lib/agent/defs.test.ts --reporter=dot
• npm run typecheck:cli
• Commit and push hooks passed.

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Tests
  • Improved alias coverage by generating test cases dynamically, helping ensure agent name matching stays consistent across more inputs.
• Chores
  • Cleaned up internal module imports without changing public behavior.

[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: 2a43cc42-e2dc-457a-9928-7b738d5c4e97

📥 Commits

Reviewing files that changed from the base of the PR and between 49f3163 and 47346db.

📒 Files selected for processing (2)

• src/lib/agent/defs.ts
• test/install-agent-alias-parity.test.ts

💤 Files with no reviewable changes (1)

• src/lib/agent/defs.ts

---

📝 Walkthrough

Walkthrough

The agent alias definitions module drops one local import while keeping its re-export. The agent alias parity test now builds expected cases from canonical mappings, normalization inputs, and the alias map instead of a fully hardcoded list.

Changes

Agent alias export and parity coverage

Layer / File(s)	Summary
Alias import cleanup src/lib/agent/defs.ts	agentAliasSummary is removed from the local ./aliases import list while remaining available through the existing re-export.
Parity cases from alias map test/install-agent-alias-parity.test.ts	ALIAS_CASES is assembled from canonical mappings, normalization inputs, and AGENT_ALIASES entries instead of a hardcoded array.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#5881: Also changes agent alias resolution and parity behavior around --agent / NEMOCLAW_AGENT.

Suggested labels

v0.0.69

Poem

🐰 I hopped through aliases, tidy and light,
One import removed, one test list made right.
Canonical carrots and variants in view,
The parity burrow now sprouts from the true.
Hop, hop, hooray! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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 is concise and correctly reflects the PR’s agent alias cleanup work.
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

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/deepagents-alias-follow-up

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the fix/deepagents-alias... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	fix/deepagents-alias... 47346db	+/-
nemoclaw/src/se...cret-scanner.ts	—	100%	—
nemoclaw/src/commands/slash.ts	—	100%	—
nemoclaw/src/li...bprocess-env.ts	—	100%	—
nemoclaw/src/bl...eprint/state.ts	—	98%	—
nemoclaw/src/onboard/config.ts	—	98%	—
nemoclaw/src/bl...int/snapshot.ts	—	97%	—
nemoclaw/src/bl...print/runner.ts	—	95%	—
nemoclaw/src/co...ration-state.ts	—	94%	—
nemoclaw/src/bl...ate-networks.ts	—	94%	—
nemoclaw/src/index.ts	—	94%	—

TypeScript / code-coverage/cli

The overall coverage in the fix/deepagents-alias... branch is 47%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	fix/deepagents-alias... 47346db	+/-
src/lib/state/o...oard-session.ts	—	91%	—
src/lib/sandbox/config.ts	—	76%	—
src/lib/actions...dbox/rebuild.ts	—	73%	—
src/lib/onboard/preflight.ts	—	62%	—
src/lib/shields/index.ts	—	62%	—
src/lib/actions...licy-channel.ts	—	60%	—
src/lib/state/sandbox.ts	—	56%	—
src/lib/policy/index.ts	—	48%	—
src/lib/onboard...er-gpu-patch.ts	—	47%	—
src/lib/onboard.ts	—	19%	—

---

_{Updated June 26, 2026 21:31 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. No E2E is recommended. This PR is effectively non-runtime: the only source change removes an unused import, and the remaining change is unit test coverage for installer/TypeScript agent alias parity. It does not modify installer/onboarding logic, sandbox lifecycle, credentials, network policy, inference routing, deployment, or assistant user flows.

Optional E2E

• None.

New E2E recommendations

• None.

[github-actions]

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: None
Optional Vitest E2E scenarios: None

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

• None. No Vitest E2E scenario dispatch is required. The production change only removes an unused import from src/lib/agent/defs.ts, and the test change is outside test/e2e-scenario/. There are no changes to scenario registry, runtime support, fixtures, live Vitest tests, manifests, workflow machinery, or onboarding resume/repair state-machine behavior.

Optional Vitest E2E scenarios

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

[github-actions]

PR Review Advisor (Nemotron Ultra) — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Add or justify PRA-T1 and any related test follow-ups.
Open items: 0 required · 0 warnings · 2 suggestions · 1 test follow-up
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Action checklist

• PRA-T1 Add or justify test follow-up: Normalization edge cases not covered in parity test
• PRA-1 In-scope improvement: Normalization edge cases not covered in parity test in test/install-agent-alias-parity.test.ts:15
• PRA-2 In-scope improvement: Overlapping PR feat(mcp): add OpenShell-managed MCP servers #5876 modifies same file — merge coordination needed in src/lib/agent/defs.ts:1

Findings index

ID	Severity	Category	Location	Required action
PRA-1	Improvement	tests	test/install-agent-alias-parity.test.ts:15	Add 4-5 normalization edge cases to NORMALIZATION_CASES: multiple spaces ("deep agents"), multiple underscores ("deep___agents"), leading/trailing dashes ("-deep-agents-"), mixed separators ("deep_agents-code"), whitespace-only.
PRA-2	Improvement	workflow	src/lib/agent/defs.ts:1	Coordinate with PR #5876 author on merge order or rebase one onto the other.

Review findings by urgency: 0 required fixes, 0 items to resolve/justify, 2 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

• None.

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

PRA-1 Improvement — Normalization edge cases not covered in parity test

• Location: test/install-agent-alias-parity.test.ts:15
• Category: tests
• Problem: The NORMALIZATION_CASES only covers 3 inputs (NEMO_DEEPAGENTS, Deep Agents, LANGCHAIN). The normalizeAgentSelector function handles multiple spaces/underscores, leading/trailing dashes, and mixed separators — these paths are not exercised in the parity test against the installer's canonical_agent_name.
• Impact: If installer normalization diverges from TypeScript normalization for edge cases, the parity test would not catch it. Low risk since core normalization is tested in defs.test.ts, but parity gap exists.
• Suggested action: Add 4-5 normalization edge cases to NORMALIZATION_CASES: multiple spaces ("deep agents"), multiple underscores ("deep___agents"), leading/trailing dashes ("-deep-agents-"), mixed separators ("deep_agents-code"), whitespace-only.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Run: npx vitest run test/install-agent-alias-parity.test.ts --reporter=verbose and verify new cases pass against both TypeScript resolver and installer canonical_agent_name.
• Missing regression test: Add test cases to NORMALIZATION_CASES array covering: ["deep agents", "langchain-deepagents-code"], ["deep___agents", "langchain-deepagents-code"], ["-deep-agents-", "langchain-deepagents-code"], ["deep_agents-code", "langchain-deepagents-code"], [" ", null] (whitespace-only should resolve to null).
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: Current NORMALIZATION_CASES at lines 15-19 only has 3 entries; normalizeAgentSelector at aliases.ts:37-42 applies trim → lowercase → replace [\s_]+ with - → collapse -+

PRA-2 Improvement — Overlapping PR #5876 modifies same file — merge coordination needed

• Location: src/lib/agent/defs.ts:1
• Category: workflow
• Problem: PR feat(mcp): add OpenShell-managed MCP servers #5876 (feat(mcp): add OpenClaw host bridge) also modifies src/lib/agent/defs.ts. This PR only removes an import (line 8), so conflict is likely trivial, but maintainers should verify merge order.
• Impact: Potential merge conflict requiring manual resolution; no semantic conflict since changes are on different lines.
• Suggested action: Coordinate with PR feat(mcp): add OpenShell-managed MCP servers #5876 author on merge order or rebase one onto the other.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Check GitHub PR feat(mcp): add OpenShell-managed MCP servers #5876 files changed list for src/lib/agent/defs.ts overlap; attempt local merge of both branches.
• Missing regression test: N/A — workflow coordination, not testable.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: pr_review_drift_context.openPrOverlaps shows PR 5876 with sameFiles: ["src/lib/agent/defs.ts"]

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

• PRA-T1 Normalization edge cases not covered in parity test — Add 4-5 normalization edge cases to NORMALIZATION_CASES: multiple spaces ("deep agents"), multiple underscores ("deep___agents"), leading/trailing dashes ("-deep-agents-"), mixed separators ("deep_agents-code"), whitespace-only.

Since last review details

Current findings, using the urgency labels above:

PRA-1 Improvement — Normalization edge cases not covered in parity test

• Location: test/install-agent-alias-parity.test.ts:15
• Category: tests
• Problem: The NORMALIZATION_CASES only covers 3 inputs (NEMO_DEEPAGENTS, Deep Agents, LANGCHAIN). The normalizeAgentSelector function handles multiple spaces/underscores, leading/trailing dashes, and mixed separators — these paths are not exercised in the parity test against the installer's canonical_agent_name.
• Impact: If installer normalization diverges from TypeScript normalization for edge cases, the parity test would not catch it. Low risk since core normalization is tested in defs.test.ts, but parity gap exists.
• Suggested action: Add 4-5 normalization edge cases to NORMALIZATION_CASES: multiple spaces ("deep agents"), multiple underscores ("deep___agents"), leading/trailing dashes ("-deep-agents-"), mixed separators ("deep_agents-code"), whitespace-only.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Run: npx vitest run test/install-agent-alias-parity.test.ts --reporter=verbose and verify new cases pass against both TypeScript resolver and installer canonical_agent_name.
• Missing regression test: Add test cases to NORMALIZATION_CASES array covering: ["deep agents", "langchain-deepagents-code"], ["deep___agents", "langchain-deepagents-code"], ["-deep-agents-", "langchain-deepagents-code"], ["deep_agents-code", "langchain-deepagents-code"], [" ", null] (whitespace-only should resolve to null).
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: Current NORMALIZATION_CASES at lines 15-19 only has 3 entries; normalizeAgentSelector at aliases.ts:37-42 applies trim → lowercase → replace [\s_]+ with - → collapse -+

PRA-2 Improvement — Overlapping PR #5876 modifies same file — merge coordination needed

• Location: src/lib/agent/defs.ts:1
• Category: workflow
• Problem: PR feat(mcp): add OpenShell-managed MCP servers #5876 (feat(mcp): add OpenClaw host bridge) also modifies src/lib/agent/defs.ts. This PR only removes an import (line 8), so conflict is likely trivial, but maintainers should verify merge order.
• Impact: Potential merge conflict requiring manual resolution; no semantic conflict since changes are on different lines.
• Suggested action: Coordinate with PR feat(mcp): add OpenShell-managed MCP servers #5876 author on merge order or rebase one onto the other.
• Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
• Verification: Check GitHub PR feat(mcp): add OpenShell-managed MCP servers #5876 files changed list for src/lib/agent/defs.ts overlap; attempt local merge of both branches.
• Missing regression test: N/A — workflow coordination, not testable.
• Done when: The local improvement is applied, or the PR notes why it should be deferred.
• Evidence: pr_review_drift_context.openPrOverlaps shows PR 5876 with sameFiles: ["src/lib/agent/defs.ts"]

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.