Document how provider prefixes prevent session ID collisions and explain
the identity-map.json feature for intentional cross-provider session sharing.
Covers:
- Default isolated session behavior (telegram: prefix)
- Why isolation prevents context confusion
- How to use identity-map.json for intentional sharing
- Provider identifier format reference
- Add Telegram handling to relay command when selected via pickProvider
- Add Telegram delivery support to agent --deliver command
- Add telegram: prefix to sender identifiers to prevent session ID collisions
- Update detectProvider to properly handle telegram: prefixed identifiers
- Document provider detection logic and session ID collision prevention
Fixes session ID collisions where Telegram users without usernames (numeric IDs
or phone numbers) were being misidentified as WhatsApp users, causing cross-
provider session leakage.
Suppress individual provider startup messages when running in
multi-provider mode to avoid duplicate/conflicting console output.
The multi-relay orchestrator provides unified startup messaging.
Changes:
- Add suppressStartMessage to WebMonitorTuning type
- Update monitorWebProvider to suppress startup message when flag set
- Update Telegram monitor to suppress initial "Starting..." message
- Pass suppressStartMessage: true from multi-relay to both providers
Console output before:
📡 Starting 2 provider(s): web, telegram
📡 Starting Telegram relay...
📡 Listening for personal WhatsApp Web inbound messages. Leave this running; Ctrl+C to stop.
✅ All 2 provider(s) active. Listening for messages... (Ctrl+C to stop)
Console output after:
📡 Starting 2 provider(s): web, telegram
✅ All 2 provider(s) active. Listening for messages... (Ctrl+C to stop)
Implements identity mapping to allow linking WhatsApp, Telegram, and Twilio
identities for shared Claude conversation sessions across providers.
Core Features:
- Identity mapping storage in ~/.clawdis/identity-map.json
- Session ID normalization for unified sessions
- CLI commands for managing identity mappings
- Full backwards compatibility (opt-in feature)
New Identity Module (src/identity/):
- types.ts: Type definitions for identity mappings
- storage.ts: CRUD operations for identity persistence
- normalize.ts: Session ID normalization logic
- Comprehensive test coverage (29 tests passing)
CLI Commands (src/commands/identity.ts):
- identity link: Link multiple provider identities
- identity list: Show all identity mappings
- identity show: Display specific mapping details
- identity unlink: Remove identity mapping
- Input validation for E.164 phone numbers and Telegram usernames
- JSON output support for list/show commands
Session Integration:
- Made deriveSessionKey() async to support identity lookups
- Updated all callers: auto-reply, agent command, web provider
- Group conversations excluded from identity mapping
- Provider detection based on ID format
Documentation:
- docs/session-sharing.md: Comprehensive user documentation
- Architecture overview and use cases
- CLI usage examples and troubleshooting guide
Test Coverage:
- src/identity/normalize.test.ts: 11 tests for normalization
- src/identity/storage.test.ts: 18 tests for storage operations
- 100% coverage of identity module functionality
Files Changed:
- 10 new files (identity module, CLI, docs, tests)
- 5 modified files (sessions, CLI integration, auto-reply)
Build Status:
- All tests passing (29/29)
- Zero TypeScript errors
- Ready for production use
- Add CONFIG_PATH_CLAWDIS (~/.clawdis/clawdis.json) as preferred path
- Keep CONFIG_PATH_LEGACY (~/.warelay/warelay.json) for backward compatibility
- Update loadConfig() to check clawdis.json first, fallback to warelay.json
- Fix TypeScript type error in extractMentionedJids (null handling)
Part of the warelay → clawdis rebranding effort.
