#8774: Fix/frontend session key normalization
app: web-ui
stale
Problem
The frontend session key input validation was overly restrictive, only accepting the three-segment agent:agentId:sessionKey format. However, the backend session key parsing logic actually supports multiple format types:
Three-segment: agent:agentId:sessionKey (e.g., agent:main:xiaohua)
Two-segment: subagent:xxx, acp:xxx (e.g., subagent:test, acp:project)
Special cases: main, global, unknown
Other two-segment formats: For extensibility
This mismatch between frontend validation and backend parsing logic caused:
Format inconsistency: Users couldn't input valid session keys that the backend supports
Poor user experience: Confusing error messages for legitimate formats
System limitations: Prevented users from using valid session key types like subagent: and acp:
Solution
Updated the frontend validation logic to match the backend's actual session key parsing requirements:
✅ Supported Formats
agent:agentId:sessionKey - Requires exactly 3 segments
subagent:xxx - Requires at least 2 segments
acp:xxx - Requires at least 2 segments
Other two-segment formats - For future extensibility
Special single-segment cases: main, global, unknown
🔧 Implementation Details
Format-specific validation: Different prefixes have different segment requirements
Visual feedback: Red border and specific error messages for invalid formats
Connection control: Disable connect button until format is valid
User guidance: Updated placeholder and tooltip with supported format examples
🎯 Validation Examples
Valid inputs:
✅ agent:main:xiaohua
✅ agent:claude:work
✅ subagent:test
✅ acp:project
✅ telegram:chat
✅ main
✅ global
Invalid inputs:
❌ xiaohua (single segment, not special case)
❌ agent:main (agent format missing third segment)
❌ subagent: (missing content after colon)
Testing
✅ Build passes successfully
✅ Gateway restart successful
✅ No linting errors
✅ Validation logic matches backend parsing in src/sessions/session-key-utils.ts
Impact
Improved UX: Users can now input all valid session key formats
System consistency: Frontend validation aligns with backend parsing logic
Better error handling: Specific error messages guide users to correct formats
Future-proof: Supports extensibility for new session key types
This fix ensures the frontend enforces proper session key formats while supporting all the formats the backend actually accepts, eliminating confusion and improving the overall user experience.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR updates the Control UI’s “Default Session Key” input to accept the backend-supported session key formats (3-part `agent:agentId:…`, 2-part prefixed keys like `subagent:`/`acp:`, and special single-token keys), adds inline validation messaging, and disables the Connect button until the value is considered valid.
The change is localized to `ui/src/ui/views/overview.ts` and aims to align frontend validation UX with backend session key parsing (`src/sessions/session-key-utils.ts`).
<h3>Confidence Score: 4/5</h3>
- This PR is generally safe to merge; issues are limited to minor frontend/backend validation mismatches that can block some inputs unnecessarily.
- Changes are UI-only and straightforward, but the new validation is slightly stricter/different than backend parsing in a couple edge cases (case sensitivity for special tokens; handling of empty segments). These are unlikely to break existing flows broadly but could frustrate some users.
- ui/src/ui/views/overview.ts
<!-- greptile_other_comments_section -->
<sub>(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#14309: fix(ui): resolve chat event session key mismatch
by justonlyforyou · 2026-02-11
82.1%
#22977: fix(ui): resolve agent names from config in session dropdown
by NikhilGaddam · 2026-02-21
82.0%
#19200: fix(cli): validate --session-id is not a session key format
by Elarwei001 · 2026-02-17
81.5%
#21679: fix: Mission Control dashboard issues for agent status, stale sessi...
by thejawdoc · 2026-02-20
80.3%
#15982: fix: pass agentId to resolveSessionFilePath in reply flow (NX-003)
by automagik-genie · 2026-02-14
79.9%
#20072: feat(sessions_spawn): add sessionKey param to reuse sub-agent sessions
by Be1Human · 2026-02-18
79.2%
#5097: fix(ui): prefer session label over displayName in dropdown
by d-init-d · 2026-01-31
78.9%
#4567: Webchat: canonicalize main session key for /new (fix #4446)
by selfboot · 2026-01-30
78.8%
#16061: fix(sessions): tolerate invalid sessionFile metadata
by haoyifan · 2026-02-14
78.6%
#8471: fix(subagent): add defensive checks for undefined string fields
by adam-smeth · 2026-02-04
78.4%