#6430: feat(protocol): include agent identity in hello-ok handshake response
app: web-ui
gateway
Resolves #6411
## Summary
Adds an optional `identity` field to the `hello-ok` handshake response payload containing the active agent's name and avatar.
## Motivation
Node apps (mobile clients, CLI tools) that connect to a gateway currently have no way to discover the active agent's identity at connect time. This forces hardcoding or extra RPC calls.
## Changes
- `src/gateway/server/ws-connection/message-handler.ts`: Resolve and include agent identity in hello-ok
- `src/gateway/protocol/schema/frames.ts`: Add optional identity field to hello-ok schema
## Details
Uses the existing `resolveAssistantIdentity()` which merges identity from:
1. `ui.assistant` config
2. Per-agent `identity` config (`agents.list[].identity`)
3. `IDENTITY.md` in agent workspace
4. Default fallback ("Assistant")
Only non-sensitive fields are included (`name`, `avatar`). Backwards compatible — clients that don't need the field can ignore it.
## Testing
The identity resolution is already well-tested via `resolveAssistantIdentity()`. The addition is a simple field inclusion in the response object.
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR extends the gateway handshake (`hello-ok`) payload to optionally include an `identity` object (`name`, optional `avatar`) so connecting clients can discover the active agent identity without an extra RPC. The protocol schema is updated accordingly, and the websocket connect handler resolves identity during the handshake response build.
Overall the change is small and backwards-compatible (new optional field), but the current implementation re-loads config during the handshake and swallows identity-resolution errors silently, which can make the response inconsistent and harder to debug if identity unexpectedly goes missing.
<h3>Confidence Score: 4/5</h3>
- This PR is likely safe to merge with low risk, but has minor implementation concerns around config consistency and diagnosability.
- Schema change is additive (optional field) and the handshake payload addition is straightforward. Main risks are redundant `loadConfig()` on the handshake hot path and the silent catch masking unexpected failures, which could lead to hard-to-debug missing identity rather than breaking functionality.
- src/gateway/server/ws-connection/message-handler.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
**Context used:**
- Context from `dashboard` - CLAUDE.md ([source](https://app.greptile.com/review/custom-context?memory=fd949e91-5c3a-4ab5-90a1-cbe184fd6ce8))
- Context from `dashboard` - AGENTS.md ([source](https://app.greptile.com/review/custom-context?memory=0d0c8278-ef8e-4d6c-ab21-f5527e322f13))
<!-- /greptile_comment -->
Most Similar PRs
#6840: Fix assistant identity default agent for global sessions
by JorgeAlan · 2026-02-02
83.1%
#9726: feat: add identityDir config for separate identity file location
by rickburn · 2026-02-05
79.9%
#11603: feat(gateway): avatar upload + config identity
by advaitpaliwal · 2026-02-08
78.1%
#7516: feat(sessions): Auto-inject From:/To: identity headers in agent-to-...
by RusDyn · 2026-02-02
75.0%
#20047: fix(googlechat): typing indicator shows 'OpenClaw' instead of agent...
by xinhuagu · 2026-02-18
74.0%
#15792: fix: pass agentId to resolveSessionFilePath in additional call sites
by MisterGuy420 · 2026-02-13
73.8%
#15982: fix: pass agentId to resolveSessionFilePath in reply flow (NX-003)
by automagik-genie · 2026-02-14
72.9%
#11497: feat(exec): inject agent identity env vars for subagents
by NOVA-Openclaw · 2026-02-07
72.1%
#8352: fix(gateway): include clientRunId in agent event payloads
by MarvinDontPanic · 2026-02-03
72.0%
#14026: gateway: expose fork/upstream identity metadata with override
by DeanoC · 2026-02-11
71.5%