fix(agent-key): restore getAgentDisplayName for HTTP-header-safe agent keys

[FuDesign2008]

Summary

• Commit 79b4b0a reintroduced ZWSP into config.agent object keys by switching remapAgentKeysToDisplayNames to call getAgentListDisplayName, which returns ZWSP-prefixed runtime names (e.g. \u200BSisyphus - Ultraworker).
• These keys are used as HTTP header values in the OpenCode /agent API; ZWSP violates RFC 7230, causing TypeError: Header 'mode_type' has invalid value.
• This is a regression of the same bug previously documented and fixed in Breaking change: ZWSP (U+200B) prefix added to agent names breaks prompt_async API consumers #3238.

Root Cause

- const displayName = getAgentListDisplayName(key)  // "\u200BSisyphus - Ultraworker" — ZWSP in key!
+ const displayName = getAgentDisplayName(key)       // "Sisyphus - Ultraworker"  — HTTP-safe

The name field inside each agent object continues to use getAgentRuntimeName(key) (with ZWSP prefix), so OpenCode's localeCompare sort ordering is fully preserved.

Changes

File	Change
src/plugin-handlers/agent-key-remapper.ts	Revert key lookup to getAgentDisplayName; name field keeps getAgentRuntimeName
src/plugin-handlers/agent-key-remapper.test.ts	Restore assertions that object keys contain no ZWSP; restore the deleted expect(name).not.toContain("\u200B") guard
src/plugin-handlers/agent-config-handler.test.ts	Revert constants to getAgentDisplayName

Testing

bun run typecheck   ✅
bun run build       ✅
bun test src/plugin-handlers/agent-key-remapper.test.ts src/plugin-handlers/agent-config-handler.test.ts
 18 pass / 0 fail   ✅

Closes #3281

---

Summary by cubic

Removes ZWSP from agent keys and name fields to keep /agent HTTP headers RFC 7230 compliant. Enforces core agent ordering via reorderAgentsByPriority (display-name matching + JS key insertion) and treats the order field as metadata only; fixes default_agent, command routing, and priority matching.

• Bug Fixes
  • Use getAgentDisplayName for agent keys, agent.name, default_agent, command agent mapping, and core priority display names; ZWSP is forbidden everywhere.
  • Update AGENTS.md to clarify ordering is guaranteed by reorderAgentsByPriority and that order is metadata; refresh tests to assert clean keys/names and verify routing/ordering against clean display names.

^{Written for commit 9bd9dfa. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Auto-approved: Fixes a regression causing HTTP header validation errors by removing ZWSP from agent keys while preserving sorting via the internal name field. Tests verify the fix.}

[FuDesign2008]

I have read the CLA Document and I hereby sign the CLA

[FuDesign2008]

Follow-up: extended ZWSP fix to three more code paths (see commit a3143d0)

After the initial fix to agent-key-remapper.ts, three more places still used getAgentListDisplayName (ZWSP-prefixed) where clean names are required:

File	Problem	Fix
agent-config-handler.ts	default_agent set to getAgentRuntimeName() → ZWSP leaked into startup display name and broke agent lookup	→ getAgentDisplayName()
agent-priority-order.ts	CORE_AGENT_ORDER.displayName used getAgentListDisplayName() for key matching → core agents not found → priority ordering silently broke	→ getAgentDisplayName()
command-config-handler.ts	cmd.agent remapped to getAgentListDisplayName() → command routing failed to resolve against clean agent keys	→ getAgentDisplayName()

All 147 tests pass after the fix.

[cubic-dev-ai]

0 issues found across 6 files (changes from recent commits).

_{Auto-approved: This PR correctly restores HTTP-safe agent keys by removing ZWSP, fixing a documented regression causing header errors while maintaining UI sort order via the internal name field.}

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/plugin-handlers/AGENTS.md">

<violation number="1" location="src/plugin-handlers/AGENTS.md:16">
P3: Don't describe `order` as the mechanism that guarantees ordering; this repo only stores it, while actual ordering still comes from display-name handling.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

_{Requires human review: PR description claims the 'name' field keeps ZWSP, but the code diff shows it is removed. This contradicts the previous requirement that ZWSP in 'name' is needed for UI sorting.}

[FuDesign2008]

Re: cubic P3 — order as ordering mechanism

Fixed in commit 9bd9dfa (docs(agent-key): clarify ordering mechanism in AGENTS.md).

Agreed with the feedback. The corrected wording now reads:

reorderAgentsByPriority iterates over CANONICAL_CORE_AGENT_ORDER, matches each core agent by display name, and inserts it first into the result object. JavaScript preserves string-key insertion order (ES2015+), so core agents always appear before custom agents regardless of alphabetical order.

The order field (integers 1-4) is stored as metadata this repo can provide — this repo only stores it; whether OpenCode consumes it for rendering is outside this codebase's control.

The actual ordering guarantee is the display-name matching loop + JS key-insertion order in reorderAgentsByPriority. The order field is supplementary metadata only.