refactor: unify social identity to user_id, eliminate entity_id

[nmhjklnm]

Background

Currently the codebase has three overlapping identity concepts:

Concept	Human value	Agent value
user_id	Supabase auth ID	—
member_id	= user_id	m_{random}
entity_id	{user_id}-1	{agent_member_id}-{seq} = thread_id

This creates unnecessary complexity: entity_id is not in the Supabase JWT, has to be derived via convention, and the -1 suffix pattern adds cognitive overhead.

Proposed Design

Social identity → user_id (unified for all participants)

• Human: user_id = Supabase auth ID (already exists)
• Agent: user_id = member_id (m_{random}) — each cloned agent gets its own ID

Agent social identity becomes per-agent, not per-thread. An agent participates in chats as itself, regardless of how many threads it has open. Cloning creates a new agent with a new identity.

member_id stays for profile/template management only — does not participate in social.

entity_id concept is eliminated — all social contexts (chats, messages, contacts, typing indicators) replace entity_id with user_id.

Scope

• DB: entities table simplified or removed; chat_entities.entity_id, chat_messages.sender_entity_id, contacts.owner_entity_id/target_entity_id, message_queue.sender_entity_id → all renamed to user_id
• Backend: ~19 files (routers, services, storage, agent layer)
• Frontend: ~8 files (auth-store.ts, types.ts, client.ts, chat pages)
• Remove get_current_entity_id dependency, replace with get_current_user_id
• Remove {user_id}-1 derivation convention

Not in scope

member_id field names in thread/panel APIs stay — member management is separate from social identity.

[shuxueshuxue]

@f-2j compare two different designs

1. use user id for both human account and its social identity
2. use a separate entity id for its social identity

[shuxueshuxue]

@f-2j compare the two identity designs once more and leave a visible GitHub reply with your conclusion

[f-2j]

@f-2j Re-compared based on current code paths; conclusion is unchanged: keep a separate entity_id as the social identity layer.

Why:

1. Auth and token model are explicitly dual-ID today (user_id + entity_id), and human entity creation is first-class ({member_id}-{seq}).
   • backend/web/services/auth_service.py lines 69-75, 127-137, 172-177.
2. API dependency layer treats entity_id as required chat/social scope, not a cosmetic alias.
   • backend/web/core/dependencies.py lines 46-52.
3. Agent thread creation binds thread identity and social identity via the same generated thread_entity_id; this is structural, not incidental.
   • backend/web/routers/threads.py lines 331-357.
4. Chat storage is keyed on entity_id (chat_entities FK to entities(id)), and core read/mute/unread logic uses it everywhere.
   • storage/providers/sqlite/chat_repo.py lines 87-170.
5. External connection state (WeChat) is persisted per entity_id by design.
   • backend/web/services/wechat_service.py lines 7-9, 131-181.
6. Docs already codify Member vs Entity separation and allow multiple entities per member.
   • docs/en/multi-agent-chat.md lines 34-40.

So design (2) is aligned with current architecture. Design (1) (user_id == social identity, remove entity_id) is possible, but it is not a small refactor; it is a cross-layer model rewrite touching auth, routing, chat schema, and integrations.

If the goal is simplification, the lower-risk path is API-level simplification (hide/derive entity_id for common human flows) while keeping entity semantics in storage and routing.

[f-2j]

Re-checked against current codebase. I still recommend design (2): keep a separate entity_id.

Why:

• Auth/login/JWT currently model both IDs explicitly (user_id + entity_id), and human social identity is created as {member_id}-{seq}.
  • backend/web/services/auth_service.py (register/login/verify token flow)
• Request scoping in web deps requires entity_id for chat/social context.
  • backend/web/core/dependencies.py
• Agent thread creation binds social identity and thread identity via generated entity IDs ({agent_member_id}-{seq}), not user IDs.
  • backend/web/routers/threads.py
• Chat storage schema and queries are centered on entity_id (chat_entities.entity_id FK + indexes + read/mute/unread paths).
  • storage/providers/sqlite/chat_repo.py
• WeChat connection state is persisted per entity_id (directory key + registry semantics).
  • backend/web/services/wechat_service.py
• Product docs also define Entity as social identity and allow multiple entities per member.
  • docs/en/multi-agent-chat.md

So removing entity_id is not a local rename; it is a cross-domain model change (auth, routing, chat schema, connection storage, docs/tests).

If the goal is reducing cognitive load, a safer path is:

1. Keep entity_id in the data model.
2. For the common human case, expose user_id as UI/API alias while preserving internal entity semantics.
3. Migrate incrementally only if we also decide to drop multi-entity-per-member capability.