feat(api-server): X-Hermes-User-* / Chat-* headers for multi-user identity

[gsskk]

Summary

Adds 6 optional headers to api_server mirroring AIAgent.__init__'s existing identity kwargs, so a single Hermes process can serve multiple end-users distinguished per-request:

Header	AIAgent kwarg
X-Hermes-User-Id	user_id
X-Hermes-User-Name	user_name
X-Hermes-Chat-Id	chat_id
X-Hermes-Chat-Name	chat_name
X-Hermes-Chat-Type	chat_type
X-Hermes-Thread-Id	thread_id

Also supports OpenAI's standard top-level user body field as a fallback for X-Hermes-User-Id (header wins if both present), so vanilla OpenAI SDK clients work without custom header config.

Headers apply to all three agent endpoints: /v1/chat/completions, /v1/responses, /v1/runs. Headers are echoed back on the response just like X-Hermes-Session-Key already is. Capabilities are advertised at /v1/capabilities so clients can feature-detect.

100% backward-compatible: requests without the new headers behave identically (same fallthrough to single-peer-per-session that native adapters bypass via the same kwargs).

Why

AIAgent already accepts user_id / user_name / chat_id / chat_name / chat_type / thread_id (run_agent.py:1097-1102). All native gateway adapters (Telegram, Discord, Slack, Matrix, …) thread these via GatewayRunner._run_agent_task (gateway/run.py:14881-14888). They drive:

• Honcho's runtime_user_peer_name resolution (run_agent.py:1967-1978 → plugins/memory/honcho/session.py:304-305), enabling per-user peer cards in multi-peer-shared-session deployments
• The session-search user_id filter (fix: enforce per-user memory/session isolation for multi-user gateway #17989 in flight)
• Memory tool's per-user ~/.hermes/memories/{chat_id}/ directory layout (also fix: enforce per-user memory/session isolation for multi-user gateway #17989)
• Per-platform peer identity routing (feat(honcho): add per-platform peer identity routing #15598 in flight)

api_server is the only adapter not threading these. After #20199 added X-Hermes-Session-Key, this is the next natural addition.

The impact today

The current api_server docs (website/docs/user-guide/features/api-server.md § Multi-User Setup with Profiles) recommend one Hermes process per user for multi-user deployments. That works but doesn't scale and blocks shared-session-multi-peer scenarios. With these headers, a single process can serve Open WebUI multi-user, LibreChat multi-tenant, chat-bot bridges (nonebot, custom Discord/Slack bridges via api_server), proxy-mode delegations, etc.

Hermes-internal beneficiary: proxy mode

gateway/run.py:_run_agent_via_proxy currently forwards only X-Hermes-Session-Id (lines 13899-13903) — user identity is dropped at the proxy boundary. This PR also patches proxy mode to forward the 6 new headers when present in the source, fixing a latent gap in Hermes's own dogfood.

Scope

Change	LOC
gateway/platforms/api_server.py — _parse_user_headers() + thread kwargs through _create_agent/_run_agent for chat_completions/responses/runs + capabilities advertise + echo on response	~80
gateway/run.py — proxy mode header forwarding	~25
tests/gateway/test_api_server.py — mirror existing test_session_key_* template	~120
website/docs/user-guide/features/api-server.md — document new headers + update Multi-User Setup section	~30

Total ~255 LOC, no new dependencies, no breaking changes, no migrations.

Prior art / related work

• feat(api-server): X-Hermes-Session-Key header for long-term memory scoping #20199 (merged): X-Hermes-Session-Key header for memory scoping — direct precedent, same shape, same _parse_*_header style
• fix(openrouter): add x-grok-conv-id header for Grok models to improve prompt cache hit rates #22708 / fix(openrouter): add x-grok-conv-id header for Grok models (carve-out of #22708) #22809 (merged): session_id plumbed through build_api_kwargs_extras for Grok cache affinity — established the "identity flows through agent transport" pattern on the outgoing side
• Matrix gateway: no in-band channel to drive per-message LLM orchestration in a downstream dispatcher #22714 (open, active): proposes complementary outgoing-side extra_body.hermes for downstream dispatcher orchestration — this PR is the incoming complement to that
• feat(api_server): per-merchant identity headers for multi-tenant deployments #12054 (open): proposes X-Hermes-Merchant-Id for tenant isolation — adjacent and compatible (tenant boundary + per-user identity within tenant)
• fix: enforce per-user memory/session isolation for multi-user gateway #17989 (open): per-user memory/session isolation in tooling — depends on this PR's user_id being passed through
• feat(honcho): add per-platform peer identity routing #15598 (open): Honcho per-platform peer identity routing — also depends on user_id being available

Field-naming alignment

chat_id (not room_id) matches Hermes's SessionSource.chat_id (gateway/session.py:84) and build_session_key output (agent:main:{platform}:group:{chat_id}:...). #22714 also moves to this naming for consistency.

What this PR does NOT include

• ❌ command_origin field from Matrix gateway: no in-band channel to drive per-message LLM orchestration in a downstream dispatcher #22714's proposal — that's outgoing-side, doesn't belong here
• ❌ X-Hermes-Merchant-Id from feat(api_server): per-merchant identity headers for multi-tenant deployments #12054 — different concern (tenant), separate PR
• ❌ Per-user memory directory creation — that's fix: enforce per-user memory/session isolation for multi-user gateway #17989's scope
• ❌ Authentication / authorization changes — reuses existing API_SERVER_KEY gate, same as X-Hermes-Session-Key

Test plan

• Unit: 6 new headers parsed, validated (control chars rejected, length capped at 256, auth required), threaded to AIAgent kwargs
• Unit: OpenAI user body field used as X-Hermes-User-Id fallback; header wins when both present
• Unit: absent headers → kwargs unset → existing single-peer fallthrough preserved
• Unit: echo-back in response headers
• Unit: /v1/capabilities advertises all 6 new *_header capabilities
• Unit: proxy mode forwards headers when source has them
• Integration: existing Honcho integration test confirmed per-user peer card formation (manual, needs Honcho instance)

Compatibility

• All existing tests pass
• No API surface changes for unmodified callers
• New headers are opt-in
• Unknown header values are silently ignored (validation only rejects control-char injection and oversized values)
• Old api_server clients sending no new headers → unchanged behavior
• New clients targeting old api_server → headers ignored gracefully

Use cases this unlocks

1. Open WebUI / LobeChat / LibreChat multi-user: one Hermes serves many web-UI users with per-user Honcho peer cards (currently requires one Hermes process per user)
2. Chat-bot bridges via api_server (nonebot, custom Discord/Slack/Telegram non-native bridges, WhatsApp via Twilio): single Hermes serves many users in many groups with proper memory scoping
3. Proxy mode (#90c98345c): forwarded calls no longer lose user identity at the api_server boundary
4. Multi-tenant SaaS Hermes deployments: one process scales to many end-users, identity-aware per request

---

Refs: #20199 (direct precedent), #22714 (outgoing-side counterpart), #12054, #17989, #15598, #14984

[gsskk]

Rebased onto current main (16613d1a6), mergeable again, gateway tests pass locally.

Context: this is the inbound half — outbound is #27525, runtime peer mapping is #30077,
all sharing the chat_id/user_id/chat_type vocabulary. See #32863 for the cleanup map.

CI still gated on external-contributor workflow approval.

[teknium1]

Thanks for the concrete API-server identity design. The underlying gap remains on current main, but there are two correctness/completeness issues to resolve before salvage.

Problems

• gateway/platforms/api_server.py:725-729 caches by Idempotency-Key and fingerprint. The chat and Responses fingerprints at :2306 and :3407 omit the new identity headers and body user; because identity changes the AIAgent/memory path, two users reusing a key with an otherwise identical body can receive a result computed under the other identity.
• Current main's /api/sessions/{session_id}/chat and /chat/stream also run agents (gateway/platforms/api_server.py:1898, :1987), but this PR only covers the three OpenAI-style endpoints. The new API-server multi-user contract should either include those routes or document the deliberate boundary.

Suggested changes

• Scope the idempotency fingerprint/key by resolved identity and add cross-identity cache regression tests for chat and Responses.
• Add /v1/runs coverage, and decide/add coverage for persisted-session chat routes.

Automated hermes-sweeper review.

[gsskk]

@teknium1 thanks for the review. Rebased onto current main and pushed d33e8c35d.

The idempotency cache is now partitioned by resolved identity: the key gets an
identity hash suffix, covering both the headers and the body user fallback
(same dict _parse_user_identity_headers produces). I scoped the key instead of
the fingerprint so retries within one identity still hit while another identity
can't read or evict the entry. No identity means the raw key is unchanged, so
existing clients see no difference. Added cross-identity regression tests for
chat and Responses, plus same-identity retry and body-user cases.

On the session routes I went with documenting the boundary: a persisted
session's identity is fixed at creation and addressed by X-Hermes-Session-Key,
so honoring a different per-request identity mid-session would fragment memory
attribution. Identity headers stay on the three stateless endpoints. Also added
the /v1/runs tests; the parsing there was already wired, just never tested.

273 gateway tests pass locally; CI still needs workflow approval.