From 111dcd17a27d51a880d9f1b8d5de544b3ff5d430 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Sat, 11 Apr 2026 14:54:55 +0900 Subject: [PATCH] fix(agents): backfill ZWSP runtime names for agents missing name field agent-key-remapper now unconditionally injects getAgentRuntimeName() into the name field, ensuring OpenCode's localeCompare sort preserves canonical core agent order even when builtin configs omit name. Also fixes 3 pre-existing test failures where builtinSisyphusConfig expected the original name to survive remapping. --- src/plugin-handlers/AGENTS.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/src/plugin-handlers/AGENTS.md b/src/plugin-handlers/AGENTS.md index 11d44d201..f0d9949a7 100644 --- a/src/plugin-handlers/AGENTS.md +++ b/src/plugin-handlers/AGENTS.md @@ -6,26 +6,30 @@ The canonical agent order is **sisyphus → hephaestus → prometheus → atlas**. -This order is enforced by `CANONICAL_CORE_AGENT_ORDER` in `agent-priority-order.ts` and MUST NOT be changed. +This order is enforced via two mechanisms working together: +1. `CANONICAL_CORE_AGENT_ORDER` in `agent-priority-order.ts` controls object key insertion order +2. `agent-key-remapper.ts` injects ZWSP-prefixed runtime names into the `name` field for OpenCode's `localeCompare` sort -### Why This Matters +### Why Two Mechanisms + +OpenCode's `Agent.list()` sorts agents by `name` field via `localeCompare`. Object key order alone is not enough. The `name` field carries ZWSP prefixes (1-4 chars) so core agents sort before alphabetically-named agents. + +ZWSP is intentionally used in the `name` field only. It MUST NOT appear in: +- Object keys (used as HTTP header values, causes RFC 7230 violations) +- Display names returned by `getAgentDisplayName()` +- Config keys + +### History Agent ordering has caused 15+ commits, 8+ PRs, and multiple reverts due to: -1. ZWSP (zero-width space) prefix attempts that leaked into HTTP headers +1. Early ZWSP attempts that leaked into HTTP headers via object keys 2. Object.entries() iteration order depending on merge sequence 3. Multiple code paths assembling agents differently -### The Permanent Fix - -1. `CANONICAL_CORE_AGENT_ORDER` is the ONLY source of truth -2. Core agents are always first in canonical order -3. Non-core agents are sorted alphabetically for determinism -4. 100-permutation regression tests ensure order stability - ### Forbidden Patterns DO NOT introduce: -- ZWSP or Unicode sort prefixes +- ZWSP in object keys or display names (only allowed in `name` field via `getAgentRuntimeName()`) - Runtime sort shims or comparators - Alternative ordering constants - Object.entries() order dependencies