@lofa199419/waha-v2 2.1.0 → 3.0.0

package/bin/waha_cli.py

@@ -17,6 +17,11 @@ DEFAULT_MAX_CHUNK_LENGTH = 1500
 SEEN_DELAY_MS = 3000
 MIN_DELAY_MS = 600
 MAX_DELAY_MS = 8000
+IDENTITY_CONTACT_PAGE_SIZE = 200
+IDENTITY_CONTACT_MAX_PAGES = 10
+IDENTITY_CHAT_LIMIT = 50
+IDENTITY_MESSAGE_LIMIT = 5
+IDENTITY_NOISY_MESSAGE_TYPES = {"ciphertext", "e2e_notification", "notification_template"}
 
 
 def env(name: str, default: str | None = None) -> str | None:
@@ -31,6 +36,11 @@ def state_dir() -> pathlib.Path:
     return home / ".openclaw"
 
 
+def identity_index_path(session_name: str) -> pathlib.Path:
+    safe = "".join(ch if ch.isalnum() or ch in "._-" else "_" for ch in (session_name or "default"))
+    return state_dir() / "extensions" / OPENCLAW_CHANNEL_ID / "identity" / f"{safe}.json"
+
+
 def parse_dotenv(path: pathlib.Path) -> dict[str, str]:
     values: dict[str, str] = {}
     if not path.exists():
@@ -201,6 +211,166 @@ def send_presence(endpoint: str, session: str, chat_id: str) -> None:
     waha_request("POST", endpoint, {"session": session, "chatId": chat_id}, session_name=session)
 
 
+def normalize_raw_id(value) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        raw = value.strip().lower()
+        return raw or None
+    if isinstance(value, dict):
+        serialized = value.get("_serialized")
+        if isinstance(serialized, str):
+            raw = serialized.strip().lower()
+            return raw or None
+    return None
+
+
+def extract_digits(value: str | None) -> str | None:
+    digits = "".join(ch for ch in str(value or "") if ch.isdigit())
+    return digits or None
+
+
+def to_chat_phone_id(value: str | None) -> str | None:
+    digits = extract_digits(value)
+    return f"{digits}@c.us" if digits else None
+
+
+def parse_jid(value) -> dict | None:
+    raw = normalize_raw_id(value)
+    if not raw:
+        return None
+    left, at, server = raw.partition("@")
+    user, colon, device = left.partition(":")
+    bare = f"{user}@{server}" if at else raw
+    kind = "unknown"
+    if server == "g.us":
+        kind = "group"
+    elif server == "broadcast":
+        kind = "broadcast"
+    elif colon:
+        kind = "device"
+    elif server == "lid":
+        kind = "lid"
+    elif server in {"c.us", "s.whatsapp.net"}:
+        kind = "direct"
+    return {
+        "raw": raw,
+        "bare": bare,
+        "server": server or None,
+        "user": user or None,
+        "device": device or None,
+        "kind": kind,
+        "phoneE164": extract_digits(user) if server in {"c.us", "s.whatsapp.net"} else None,
+        "lid": bare if server == "lid" else None,
+    }
+
+
+def add_alias(target: set[str], raw_value) -> None:
+    parsed = parse_jid(raw_value)
+    if not parsed:
+        return
+    target.add(parsed["raw"])
+    target.add(parsed["bare"])
+    if parsed.get("phoneE164"):
+        target.add(f"{parsed['phoneE164']}@c.us")
+
+
+def merge_preferred_text(current: str | None, nxt: str | None) -> str | None:
+    nxt = str(nxt or "").strip()
+    if not nxt:
+        return current
+    current = str(current or "").strip()
+    return current or nxt
+
+
+def merge_preferred_phone(current: str | None, nxt: str | None) -> str | None:
+    return current or extract_digits(nxt)
+
+
+def extract_name(record) -> str | None:
+    if not isinstance(record, dict):
+        return None
+    business = record.get("businessProfile")
+    candidates = [
+        record.get("name"),
+        record.get("pushname"),
+        record.get("shortName"),
+        record.get("verifiedName"),
+        business.get("verifiedName") if isinstance(business, dict) else None,
+        record.get("subject"),
+    ]
+    for candidate in candidates:
+        text = str(candidate or "").strip()
+        if text:
+            return text
+    return None
+
+
+def pick_message_body(record: dict) -> str | None:
+    direct = str(record.get("body") or "").strip()
+    if direct:
+        return direct
+    nested = record.get("_data")
+    if isinstance(nested, dict):
+        nested_body = str(nested.get("body") or "").strip()
+        if nested_body:
+            return nested_body
+    return None
+
+
+def sanitize_message_body(body: str | None, message_type: str | None) -> str | None:
+    text = str(body or "").strip()
+    if not text:
+        return None
+    compact = "".join(text.split())
+    binary_like = (
+        len(compact) > 160
+        and len(compact) % 4 == 0
+        and all(ch.isalnum() or ch in "+/=" for ch in compact)
+        and (compact.startswith("/9j/") or compact.startswith("iVBOR") or compact.startswith("UklGR"))
+    )
+    if binary_like:
+        return None
+    if str(message_type or "").strip().lower() in IDENTITY_NOISY_MESSAGE_TYPES:
+        return None
+    return text
+
+
+def summarize_recent_messages(values, self_aliases: set[str]) -> list[dict]:
+    summaries: list[dict] = []
+    if not isinstance(values, list):
+        return summaries
+    for value in values:
+        if not isinstance(value, dict):
+            continue
+        nested = value.get("_data")
+        nested = nested if isinstance(nested, dict) else {}
+        raw_from = normalize_raw_id(value.get("from") or nested.get("from"))
+        raw_to = normalize_raw_id(value.get("to") or nested.get("to"))
+        raw_type = str(value.get("type") or nested.get("type") or "").strip() or None
+        timestamp = value.get("timestamp")
+        if not isinstance(timestamp, int):
+            timestamp = nested.get("t") if isinstance(nested.get("t"), int) else None
+        from_me = value.get("fromMe") is True
+        direction = "out" if from_me or (raw_from and (raw_from in self_aliases or (parse_jid(raw_from) or {}).get("bare") in self_aliases)) else "in"
+        body = sanitize_message_body(pick_message_body(value), raw_type)
+        if str(raw_type or "").lower() in IDENTITY_NOISY_MESSAGE_TYPES and not body:
+            continue
+        summaries.append(
+            {
+                "id": str(value.get("id") or "").strip() or None,
+                "timestamp": timestamp,
+                "direction": direction,
+                "from": raw_from,
+                "to": raw_to,
+                "body": body,
+                "type": raw_type,
+                "hasMedia": value.get("hasMedia") is True,
+            }
+        )
+    return summaries
+
+
 def waha_request(method: str, path: str, body: dict | None = None, query: dict | None = None, session_name: str | None = None):
     base_url = normalize_base_url(require_resolved("WAHA_URL", session_name))
     api_key = require_resolved("WAHA_API_KEY", session_name)
@@ -270,6 +440,7 @@ Chats and Messages:
   waha-get-chats [--session NAME] [--limit N] [--offset N]
   waha-get-messages --chat-id ID [--session NAME] [--limit N] [--offset N]
   waha-send-text --chat-id ID --text TEXT [--session NAME]
+  waha-rebuild-identity-index [--session NAME]
 
 Optional env:
   WAHA_SESSION_DEFAULT / WAHA_DEFAULT_SESSION
@@ -477,6 +648,203 @@ def cmd_send_text(args):
             print(f"Chunk {index} Message ID: {message_id}")
 
 
+def cmd_rebuild_identity_index(args):
+    session = args.session
+    lid_rows = waha_request(
+        "GET",
+        f"/api/{urllib.parse.quote(session, safe='')}/lids",
+        session_name=session,
+    )
+    lid_rows = lid_rows if isinstance(lid_rows, list) else []
+    lid_mappings: dict[str, str] = {}
+    phone_to_lid: dict[str, str] = {}
+    for row in lid_rows:
+        if not isinstance(row, dict):
+            continue
+        lid = normalize_raw_id(row.get("lid"))
+        pn = normalize_raw_id(row.get("pn")) or to_chat_phone_id(str(row.get("pn") or ""))
+        if not lid or not pn:
+            continue
+        lid_mappings[lid] = pn
+        phone_to_lid[pn] = lid
+
+    contacts: list[dict] = []
+    for page in range(IDENTITY_CONTACT_MAX_PAGES):
+        offset = page * IDENTITY_CONTACT_PAGE_SIZE
+        batch = waha_request(
+            "GET",
+            "/api/contacts/all",
+            query={"session": session, "limit": IDENTITY_CONTACT_PAGE_SIZE, "offset": offset},
+            session_name=session,
+        )
+        if not isinstance(batch, list) or not batch:
+            break
+        contacts.extend(item for item in batch if isinstance(item, dict))
+        if len(batch) < IDENTITY_CONTACT_PAGE_SIZE:
+            break
+
+    self_aliases: set[str] = set()
+    self_display_name = None
+    self_phone = None
+    for contact in contacts:
+        if contact.get("isMe") is not True:
+            continue
+        add_alias(self_aliases, contact.get("id"))
+        self_phone = merge_preferred_phone(self_phone, str(contact.get("number") or ""))
+        self_display_name = merge_preferred_text(self_display_name, extract_name(contact))
+
+    peers: dict[str, dict] = {}
+    lookup: dict[str, str] = {}
+    canonical: dict[str, str] = {}
+
+    def upsert_peer(chat_id: str, patch: dict, alias_ids: set[str] | None = None) -> None:
+        parsed = parse_jid(chat_id) or {}
+        existing = peers.get(chat_id, {
+            "chatId": chat_id,
+            "kind": parsed.get("kind", "unknown"),
+            "aliases": [],
+            "recentMessages": [],
+            "updatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        })
+        alias_set = set(existing.get("aliases", []))
+        add_alias(alias_set, chat_id)
+        for alias in alias_ids or set():
+            add_alias(alias_set, alias)
+        next_peer = dict(existing)
+        next_peer.update(patch)
+        next_peer["kind"] = patch.get("kind", existing.get("kind", "unknown"))
+        next_peer["displayName"] = merge_preferred_text(existing.get("displayName"), patch.get("displayName"))
+        next_peer["verifiedName"] = merge_preferred_text(existing.get("verifiedName"), patch.get("verifiedName"))
+        next_peer["phoneE164"] = merge_preferred_phone(existing.get("phoneE164"), patch.get("phoneE164"))
+        next_peer["lid"] = merge_preferred_text(existing.get("lid"), patch.get("lid"))
+        next_peer["aliases"] = sorted(alias_set)
+        next_peer["recentMessages"] = patch.get("recentMessages", existing.get("recentMessages", []))
+        next_peer["lastMessageAt"] = patch.get("lastMessageAt", existing.get("lastMessageAt"))
+        next_peer["updatedAt"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        peers[chat_id] = next_peer
+        for alias in next_peer["aliases"]:
+            lookup[alias] = chat_id
+            parsed_alias = parse_jid(alias) or {}
+            if parsed_alias.get("kind") == "lid":
+                mapped_phone = lid_mappings.get(parsed_alias.get("bare"))
+                if mapped_phone:
+                    canonical[alias] = mapped_phone
+            elif parsed_alias.get("kind") == "direct" and parsed_alias.get("phoneE164"):
+                canonical[alias] = f"{parsed_alias['phoneE164']}@c.us"
+        lookup[chat_id] = chat_id
+        if next_peer.get("phoneE164"):
+            canonical[f"{next_peer['phoneE164']}@c.us"] = f"{next_peer['phoneE164']}@c.us"
+        if next_peer.get("lid") and lid_mappings.get(next_peer["lid"]):
+            canonical[next_peer["lid"]] = lid_mappings[next_peer["lid"]]
+
+    for contact in contacts:
+        contact_id = normalize_raw_id(contact.get("id"))
+        if not contact_id:
+            continue
+        parsed = parse_jid(contact_id) or {}
+        aliases: set[str] = set()
+        add_alias(aliases, contact_id)
+        business = contact.get("businessProfile")
+        if isinstance(business, dict):
+            add_alias(aliases, business.get("id"))
+        phone_digits = extract_digits(str(contact.get("number") or "")) if parsed.get("kind") == "direct" else None
+        if phone_digits:
+            aliases.add(f"{phone_digits}@c.us")
+        upsert_peer(
+            contact_id,
+            {
+                "kind": parsed.get("kind", "unknown"),
+                "displayName": extract_name(contact),
+                "verifiedName": str(contact.get("verifiedName") or "").strip() or None,
+                "phoneE164": parsed.get("phoneE164") or phone_digits,
+                "lid": parsed.get("lid"),
+            },
+            aliases,
+        )
+
+    chats = waha_request(
+        "GET",
+        f"/api/{urllib.parse.quote(session, safe='')}/chats",
+        query={"limit": IDENTITY_CHAT_LIMIT, "offset": 0},
+        session_name=session,
+    )
+    chats = chats if isinstance(chats, list) else []
+    for chat in chats:
+        if not isinstance(chat, dict):
+            continue
+        chat_id = normalize_raw_id(chat.get("id") or chat.get("chatId"))
+        if not chat_id:
+            continue
+        parsed_chat = parse_jid(chat_id) or {}
+        messages = waha_request(
+            "GET",
+            f"/api/{urllib.parse.quote(session, safe='')}/chats/{urllib.parse.quote(chat_id, safe='')}/messages",
+            query={"limit": IDENTITY_MESSAGE_LIMIT},
+            session_name=session,
+        )
+        summaries = summarize_recent_messages(messages if isinstance(messages, list) else [], self_aliases)
+        alias_set: set[str] = set()
+        add_alias(alias_set, chat_id)
+        resolved_phone = parsed_chat.get("phoneE164")
+        resolved_lid = parsed_chat.get("lid")
+        if parsed_chat.get("lid") and lid_mappings.get(parsed_chat["lid"]):
+            resolved_phone = merge_preferred_phone(resolved_phone, lid_mappings.get(parsed_chat["lid"]))
+        if parsed_chat.get("kind") == "direct" and parsed_chat.get("phoneE164"):
+            direct_chat_id = f"{parsed_chat['phoneE164']}@c.us"
+            if direct_chat_id in phone_to_lid:
+                resolved_lid = merge_preferred_text(resolved_lid, phone_to_lid[direct_chat_id])
+        for message in summaries:
+            counterpart_id = message.get("to") if message.get("direction") == "out" else message.get("from")
+            counterpart_raw = normalize_raw_id(counterpart_id)
+            counterpart_parsed = parse_jid(counterpart_id) or {}
+            if counterpart_raw and counterpart_raw not in self_aliases and counterpart_parsed.get("bare") not in self_aliases:
+                add_alias(alias_set, counterpart_raw)
+            resolved_phone = merge_preferred_phone(resolved_phone, counterpart_parsed.get("phoneE164"))
+            resolved_lid = merge_preferred_text(resolved_lid, counterpart_parsed.get("lid"))
+            if counterpart_parsed.get("lid") and lid_mappings.get(counterpart_parsed["lid"]):
+                resolved_phone = merge_preferred_phone(resolved_phone, lid_mappings.get(counterpart_parsed["lid"]))
+            if counterpart_parsed.get("kind") == "direct" and counterpart_parsed.get("phoneE164"):
+                direct_counterpart_id = f"{counterpart_parsed['phoneE164']}@c.us"
+                if direct_counterpart_id in phone_to_lid:
+                    resolved_lid = merge_preferred_text(resolved_lid, phone_to_lid[direct_counterpart_id])
+        upsert_peer(
+            chat_id,
+            {
+                "kind": "group" if chat.get("isGroup") is True else parsed_chat.get("kind", "unknown"),
+                "displayName": extract_name(chat),
+                "phoneE164": resolved_phone,
+                "lid": resolved_lid,
+                "recentMessages": summaries,
+                "lastMessageAt": summaries[0]["timestamp"] if summaries else None,
+            },
+            alias_set,
+        )
+
+    index = {
+        "version": 1,
+        "accountId": session,
+        "session": session,
+        "refreshedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "stateDir": str(state_dir()),
+        "self": {
+            "displayName": self_display_name,
+            "phoneE164": self_phone,
+            "aliases": sorted(self_aliases),
+        } if self_aliases or self_display_name or self_phone else None,
+        "peers": dict(sorted(peers.items())),
+        "lookup": dict(sorted(lookup.items())),
+        "canonical": dict(sorted(canonical.items())),
+        "lidMappings": dict(sorted(lid_mappings.items())),
+    }
+    path = identity_index_path(session)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(index, indent=2, ensure_ascii=False) + "\n")
+    print(f"Identity index rebuilt for session '{session}'.")
+    print(f"Path: {path}")
+    print(f"Peers: {len(peers)}")
+    print(f"LID mappings: {len(lid_mappings)}")
+
+
 COMMANDS = {
     "waha-list-sessions": ("List sessions", cmd_list_sessions),
     "waha-get-session": ("Get session", cmd_get_session),
@@ -493,6 +861,7 @@ COMMANDS = {
     "waha-list-chats": ("List chats", cmd_get_chats),
     "waha-get-messages": ("Get messages", cmd_get_messages),
     "waha-send-text": ("Send text", cmd_send_text),
+    "waha-rebuild-identity-index": ("Rebuild identity index", cmd_rebuild_identity_index),
 }
 
 
@@ -518,6 +887,8 @@ def command_parser(command: str):
         add_session_arg(parser)
         parser.add_argument("--chat-id", required=True)
         parser.add_argument("--text", required=True)
+    elif command == "waha-rebuild-identity-index":
+        add_session_arg(parser)
     return parser
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lofa199419/waha-v2",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "private": false,
   "description": "OpenClaw WAHA v2 channel plugin — independent WhatsApp HTTP API integration",
   "type": "module",

package/src/client.ts

@@ -25,6 +25,11 @@ export type WahaV2PollPayload = {
   multipleAnswers?: boolean;
 };
 
+export type WahaV2LidMapping = {
+  lid?: string;
+  pn?: string;
+};
+
 export class WahaV2Client {
   private readonly inner: WahaClient;
   private readonly _config: WahaV2ClientConfig;
@@ -107,6 +112,59 @@ export class WahaV2Client {
     }
   }
 
+  async listLidMappings(session: string): Promise<WahaV2LidMapping[]> {
+    const url = `${this._config.baseUrl}/api/${encodeURIComponent(session)}/lids`;
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (this._config.apiKey) headers["X-Api-Key"] = this._config.apiKey;
+    const response = await fetch(url, { method: "GET", headers });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      const suffix = body ? ` body=${body.slice(0, 240)}` : "";
+      throw new Error(`WAHA /lids lookup failed: ${response.status} ${response.statusText}${suffix}`);
+    }
+    const json = (await response.json().catch(() => [])) as unknown;
+    return Array.isArray(json) ? (json as WahaV2LidMapping[]) : [];
+  }
+
+  async getPhoneNumberByLid(session: string, lid: string): Promise<WahaV2LidMapping | undefined> {
+    const url = `${this._config.baseUrl}/api/${encodeURIComponent(session)}/lids/${encodeURIComponent(lid)}`;
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (this._config.apiKey) headers["X-Api-Key"] = this._config.apiKey;
+    const response = await fetch(url, { method: "GET", headers });
+    if (response.status === 404) return undefined;
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      const suffix = body ? ` body=${body.slice(0, 240)}` : "";
+      throw new Error(
+        `WAHA /lids/{lid} lookup failed: ${response.status} ${response.statusText}${suffix}`,
+      );
+    }
+    return (await response.json().catch(() => undefined)) as WahaV2LidMapping | undefined;
+  }
+
+  async getLidByPhoneNumber(
+    session: string,
+    phoneNumberOrChatId: string,
+  ): Promise<WahaV2LidMapping | undefined> {
+    const normalized = String(phoneNumberOrChatId ?? "").trim().toLowerCase();
+    const phoneNumber = normalized.endsWith("@c.us")
+      ? normalized.slice(0, -5)
+      : normalized.replace(/\D+/g, "");
+    const url = `${this._config.baseUrl}/api/${encodeURIComponent(session)}/lids/pn/${encodeURIComponent(phoneNumber)}`;
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (this._config.apiKey) headers["X-Api-Key"] = this._config.apiKey;
+    const response = await fetch(url, { method: "GET", headers });
+    if (response.status === 404) return undefined;
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      const suffix = body ? ` body=${body.slice(0, 240)}` : "";
+      throw new Error(
+        `WAHA /lids/pn/{phone} lookup failed: ${response.status} ${response.statusText}${suffix}`,
+      );
+    }
+    return (await response.json().catch(() => undefined)) as WahaV2LidMapping | undefined;
+  }
+
   // ---------------------------------------------------------------------------
   // Session management
   // ---------------------------------------------------------------------------

package/src/gateway.ts

@@ -1,5 +1,6 @@
 import type { ChannelGatewayAdapter } from "openclaw/plugin-sdk";
 import { createWahaV2Client } from "./client.js";
+import { warmWahaV2IdentityIndex } from "./identity.js";
 import { probeWahaV2Session } from "./probe.js";
 import { getWahaV2Logger } from "./runtime.js";
 import { removeWahaV2Client, setWahaV2Client } from "./runtime.js";
@@ -132,11 +133,20 @@ export const wahaV2Gateway: ChannelGatewayAdapter<ResolvedWahaV2Account> = {
         `baseUrl=${account.baseUrl} session=${account.session} connected=${probe.ok}`,
     );
 
+    if (probe.ok && !abortSignal.aborted) {
+      void warmWahaV2IdentityIndex(client, account, "startup").catch(() => {});
+    }
+
     // Health monitoring — re-probe every 60 s and update connected state.
+    let lastConnected = probe.ok;
     let healthInterval: ReturnType<typeof setInterval> | null = setInterval(async () => {
       if (abortSignal.aborted) return;
       const health = await probeWahaV2Session(client, account.session).catch(() => ({ ok: false }));
       setStatus({ accountId: account.accountId, running: true, connected: health.ok });
+      if (health.ok && !lastConnected) {
+        void warmWahaV2IdentityIndex(client, account, "reconnected").catch(() => {});
+      }
+      lastConnected = health.ok;
     }, HEALTH_INTERVAL_MS);
 
     abortSignal.addEventListener(

package/src/identity.ts

@@ -0,0 +1,674 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { WahaV2Client, WahaV2LidMapping } from "./client.js";
+import { getWahaV2Logger } from "./runtime.js";
+import type { ResolvedWahaV2Account } from "./types.js";
+
+const IDENTITY_INDEX_VERSION = 1;
+const CONTACT_PAGE_SIZE = 200;
+const CONTACT_MAX_PAGES = 10;
+const CHAT_SYNC_LIMIT = 50;
+const RECENT_MESSAGE_LIMIT = 5;
+const NOISY_MESSAGE_TYPES = new Set(["ciphertext", "e2e_notification", "notification_template"]);
+
+type WahaPeerKind = "direct" | "group" | "lid" | "device" | "broadcast" | "unknown";
+
+type WahaParsedJid = {
+  raw: string;
+  bare: string;
+  server?: string;
+  user?: string;
+  device?: string;
+  kind: WahaPeerKind;
+  phoneE164?: string;
+  lid?: string;
+};
+
+export type WahaV2IdentityMessageSummary = {
+  id?: string;
+  timestamp?: number;
+  direction: "in" | "out";
+  from?: string;
+  to?: string;
+  body?: string;
+  type?: string;
+  hasMedia?: boolean;
+};
+
+export type WahaV2IdentityPeerRecord = {
+  chatId: string;
+  kind: WahaPeerKind;
+  displayName?: string;
+  verifiedName?: string;
+  phoneE164?: string;
+  lid?: string;
+  aliases: string[];
+  recentMessages: WahaV2IdentityMessageSummary[];
+  lastMessageAt?: number;
+  updatedAt: string;
+};
+
+export type WahaV2IdentityIndex = {
+  version: number;
+  accountId: string;
+  session: string;
+  refreshedAt: string;
+  stateDir: string;
+  self?: {
+    displayName?: string;
+    phoneE164?: string;
+    aliases: string[];
+  };
+  peers: Record<string, WahaV2IdentityPeerRecord>;
+  lookup: Record<string, string>;
+  canonical: Record<string, string>;
+  lidMappings: Record<string, string>;
+};
+
+export type WahaV2ResolvedIdentity = {
+  chat?: WahaV2IdentityPeerRecord;
+  sender?: WahaV2IdentityPeerRecord;
+  canonicalChatId?: string;
+  canonicalSenderId?: string;
+  indexPath: string;
+};
+
+const identityCache = new Map<string, WahaV2IdentityIndex>();
+const warmInFlight = new Map<string, Promise<WahaV2IdentityIndex>>();
+
+function cacheKey(account: { accountId: string; session: string }): string {
+  return `${account.accountId}:${account.session}`;
+}
+
+function sanitizeFileComponent(value: string): string {
+  const cleaned = String(value ?? "").trim();
+  return (cleaned || "default").replace(/[^a-z0-9._-]+/gi, "_");
+}
+
+function extractDigits(value: string | undefined): string | undefined {
+  const digits = String(value ?? "").replace(/\D+/g, "");
+  return digits || undefined;
+}
+
+function normalizeRawId(value: unknown): string | undefined {
+  if (!value) return undefined;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    return normalized || undefined;
+  }
+  if (typeof value === "object") {
+    const serialized = (value as { _serialized?: unknown })._serialized;
+    if (typeof serialized === "string") {
+      const normalized = serialized.trim().toLowerCase();
+      return normalized || undefined;
+    }
+  }
+  return undefined;
+}
+
+function toChatPhoneId(value: string | undefined): string | undefined {
+  const digits = extractDigits(value);
+  return digits ? `${digits}@c.us` : undefined;
+}
+
+function parseJid(rawValue: unknown): WahaParsedJid | undefined {
+  const raw = normalizeRawId(rawValue);
+  if (!raw) return undefined;
+
+  const [left, server] = raw.split("@", 2);
+  const [user, device] = String(left ?? "").split(":", 2);
+  const bare = server ? `${user}@${server}` : raw;
+  const baseDigits = extractDigits(user);
+
+  let kind: WahaPeerKind = "unknown";
+  if (server === "g.us") kind = "group";
+  else if (server === "broadcast") kind = "broadcast";
+  else if (device) kind = "device";
+  else if (server === "lid") kind = "lid";
+  else if (server === "c.us" || server === "s.whatsapp.net") kind = "direct";
+
+  return {
+    raw,
+    bare,
+    server,
+    user: user || undefined,
+    device: device || undefined,
+    kind,
+    phoneE164: server === "c.us" || server === "s.whatsapp.net" ? baseDigits : undefined,
+    lid: server === "lid" ? bare : undefined,
+  };
+}
+
+function extractName(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const record = value as Record<string, unknown>;
+  const candidates = [
+    record.name,
+    record.pushname,
+    record.shortName,
+    record.verifiedName,
+    (record.businessProfile as Record<string, unknown> | undefined)?.verifiedName,
+    record.subject,
+  ];
+  for (const candidate of candidates) {
+    const text = String(candidate ?? "").trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
+function pickMessageBody(value: Record<string, unknown>): string | undefined {
+  const direct = String(value.body ?? "").trim();
+  if (direct) return direct;
+  const nested = value._data as Record<string, unknown> | undefined;
+  const nestedBody = String(nested?.body ?? "").trim();
+  if (nestedBody) return nestedBody;
+  return undefined;
+}
+
+function sanitizeMessageBody(body: string | undefined, type?: string): string | undefined {
+  const text = String(body ?? "").trim();
+  if (!text) return undefined;
+  const compact = text.replace(/\s+/g, "");
+  const binaryLike =
+    compact.length > 160 &&
+    compact.length % 4 === 0 &&
+    /^[A-Za-z0-9+/=]+$/.test(compact) &&
+    (compact.startsWith("/9j/") || compact.startsWith("iVBOR") || compact.startsWith("UklGR"));
+  if (binaryLike) return undefined;
+  if (NOISY_MESSAGE_TYPES.has(String(type ?? "").trim().toLowerCase())) return undefined;
+  return text;
+}
+
+function summarizeRecentMessages(
+  values: unknown[],
+  selfAliases: Set<string>,
+): WahaV2IdentityMessageSummary[] {
+  if (!Array.isArray(values)) return [];
+  const summaries: WahaV2IdentityMessageSummary[] = [];
+  for (const value of values) {
+    if (!value || typeof value !== "object") continue;
+    const record = value as Record<string, unknown>;
+    const nested = record._data as Record<string, unknown> | undefined;
+    const rawFrom = normalizeRawId(record.from ?? nested?.from);
+    const rawTo = normalizeRawId(record.to ?? nested?.to);
+    const fromMe = record.fromMe === true;
+    const timestamp =
+      typeof record.timestamp === "number"
+        ? record.timestamp
+        : typeof nested?.t === "number"
+          ? (nested.t as number)
+          : undefined;
+    const rawType = String(record.type ?? nested?.type ?? "").trim() || undefined;
+    const direction: "in" | "out" =
+      fromMe || (rawFrom ? selfAliases.has(rawFrom) || selfAliases.has(parseJid(rawFrom)?.bare ?? "") : false)
+        ? "out"
+        : "in";
+    const sanitizedBody = sanitizeMessageBody(pickMessageBody(record), rawType);
+    if (NOISY_MESSAGE_TYPES.has(String(rawType ?? "").toLowerCase()) && !sanitizedBody) {
+      continue;
+    }
+
+    summaries.push({
+      id: String(record.id ?? "").trim() || undefined,
+      timestamp,
+      direction,
+      from: rawFrom,
+      to: rawTo,
+      body: sanitizedBody,
+      type: rawType,
+      hasMedia: record.hasMedia === true,
+    });
+  }
+  return summaries;
+}
+
+function addAlias(target: Set<string>, rawValue: unknown): void {
+  const parsed = parseJid(rawValue);
+  if (!parsed) return;
+  target.add(parsed.raw);
+  target.add(parsed.bare);
+  if (parsed.phoneE164) {
+    target.add(`${parsed.phoneE164}@c.us`);
+  }
+}
+
+function normalizeLidMapping(value: WahaV2LidMapping | undefined): WahaV2LidMapping | undefined {
+  if (!value) return undefined;
+  const lid = normalizeRawId(value.lid);
+  const pn = normalizeRawId(value.pn) ?? toChatPhoneId(String(value.pn ?? ""));
+  if (!lid && !pn) return undefined;
+  return { lid, pn };
+}
+
+function resolveStateDir(): string {
+  const configured = String(process.env.OPENCLAW_STATE_DIR ?? "").trim();
+  return configured || join(homedir(), ".openclaw");
+}
+
+function resolveIdentityIndexPath(account: { session: string }): string {
+  return join(
+    resolveStateDir(),
+    "extensions",
+    "waha-v2",
+    "identity",
+    `${sanitizeFileComponent(account.session)}.json`,
+  );
+}
+
+async function writeIdentityIndex(index: WahaV2IdentityIndex): Promise<void> {
+  const path = resolveIdentityIndexPath(index);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(index, null, 2)}\n`, "utf8");
+}
+
+function formatRecentMessageForAgent(message: WahaV2IdentityMessageSummary): string {
+  const direction = message.direction === "out" ? "out" : "in";
+  const timestamp = message.timestamp
+    ? new Date(message.timestamp * 1000).toISOString()
+    : "unknown-time";
+  const body = String(message.body ?? "").replace(/\s+/g, " ").trim();
+  const summary = body || `[${message.type ?? (message.hasMedia ? "media" : "message")}]`;
+  return `- ${direction} ${timestamp} ${summary.slice(0, 180)}`;
+}
+
+function mergePreferredText(current: string | undefined, next: string | undefined): string | undefined {
+  const candidate = String(next ?? "").trim();
+  if (!candidate) return current;
+  const existing = String(current ?? "").trim();
+  return existing || candidate;
+}
+
+function mergePreferredPhone(current: string | undefined, next: string | undefined): string | undefined {
+  return current ?? extractDigits(next);
+}
+
+async function buildIdentityIndex(
+  client: WahaV2Client,
+  account: ResolvedWahaV2Account,
+): Promise<WahaV2IdentityIndex> {
+  const lidMappingEntries = await client.listLidMappings(account.session).catch((err) => {
+    getWahaV2Logger().warn(
+      `waha-v2: identity lid sync failed for session "${account.session}": ${String(err)}`,
+    );
+    return [];
+  });
+  const lidMappings = new Map<string, string>();
+  const phoneToLid = new Map<string, string>();
+  for (const entry of lidMappingEntries) {
+    const normalized = normalizeLidMapping(entry);
+    if (!normalized?.lid || !normalized.pn) continue;
+    lidMappings.set(normalized.lid, normalized.pn);
+    phoneToLid.set(normalized.pn, normalized.lid);
+  }
+
+  const contacts: unknown[] = [];
+  for (let page = 0; page < CONTACT_MAX_PAGES; page += 1) {
+    const offset = page * CONTACT_PAGE_SIZE;
+    const current = await client.listContacts(account.session, CONTACT_PAGE_SIZE, offset).catch((err) => {
+      getWahaV2Logger().warn(
+        `waha-v2: identity contact sync failed for session "${account.session}" at offset ${offset}: ${String(err)}`,
+      );
+      return [];
+    });
+    if (!Array.isArray(current) || current.length === 0) break;
+    contacts.push(...current);
+    if (current.length < CONTACT_PAGE_SIZE) break;
+  }
+
+  const selfAliasSet = new Set<string>();
+  const selfDisplayNames: string[] = [];
+  let selfPhoneE164: string | undefined;
+
+  for (const contact of contacts) {
+    if (!contact || typeof contact !== "object") continue;
+    const record = contact as Record<string, unknown>;
+    if (record.isMe !== true) continue;
+    addAlias(selfAliasSet, record.id);
+    selfPhoneE164 = mergePreferredPhone(selfPhoneE164, String(record.number ?? ""));
+    const displayName = extractName(record);
+    if (displayName) selfDisplayNames.push(displayName);
+  }
+
+  const peers = new Map<string, WahaV2IdentityPeerRecord>();
+  const lookup = new Map<string, string>();
+  const canonical = new Map<string, string>();
+
+  const upsertPeer = (chatId: string, patch: Partial<WahaV2IdentityPeerRecord>, aliasIds?: Iterable<string>) => {
+    const parsed = parseJid(chatId);
+    const existing =
+      peers.get(chatId) ??
+      ({
+        chatId,
+        kind: parsed?.kind ?? "unknown",
+        aliases: [],
+        recentMessages: [],
+        updatedAt: new Date().toISOString(),
+      } satisfies WahaV2IdentityPeerRecord);
+
+    const aliasSet = new Set(existing.aliases);
+    addAlias(aliasSet, chatId);
+    if (aliasIds) {
+      for (const alias of aliasIds) {
+        addAlias(aliasSet, alias);
+      }
+    }
+
+    const next: WahaV2IdentityPeerRecord = {
+      ...existing,
+      ...patch,
+      kind: patch.kind ?? existing.kind,
+      displayName: mergePreferredText(existing.displayName, patch.displayName),
+      verifiedName: mergePreferredText(existing.verifiedName, patch.verifiedName),
+      phoneE164: mergePreferredPhone(existing.phoneE164, patch.phoneE164),
+      lid: mergePreferredText(existing.lid, patch.lid),
+      aliases: Array.from(aliasSet).sort(),
+      recentMessages: patch.recentMessages ?? existing.recentMessages,
+      lastMessageAt: patch.lastMessageAt ?? existing.lastMessageAt,
+      updatedAt: new Date().toISOString(),
+    };
+    peers.set(chatId, next);
+    for (const alias of next.aliases) {
+      lookup.set(alias, chatId);
+    }
+    lookup.set(chatId, chatId);
+    if (next.phoneE164) {
+      canonical.set(`${next.phoneE164}@c.us`, `${next.phoneE164}@c.us`);
+    }
+    if (next.lid) {
+      const mappedPhone = lidMappings.get(next.lid);
+      if (mappedPhone) canonical.set(next.lid, mappedPhone);
+    }
+    for (const alias of next.aliases) {
+      const parsedAlias = parseJid(alias);
+      if (parsedAlias?.kind === "lid") {
+        const mappedPhone = lidMappings.get(parsedAlias.bare);
+        if (mappedPhone) canonical.set(alias, mappedPhone);
+      } else if (parsedAlias?.kind === "direct" && parsedAlias.phoneE164) {
+        canonical.set(alias, `${parsedAlias.phoneE164}@c.us`);
+      }
+    }
+  };
+
+  for (const contact of contacts) {
+    if (!contact || typeof contact !== "object") continue;
+    const record = contact as Record<string, unknown>;
+    const contactId = normalizeRawId(record.id);
+    if (!contactId) continue;
+    const parsed = parseJid(contactId);
+    const aliases = new Set<string>();
+    addAlias(aliases, contactId);
+    const businessId = normalizeRawId((record.businessProfile as Record<string, unknown> | undefined)?.id);
+    if (businessId) addAlias(aliases, businessId);
+    const phoneDigits =
+      parsed?.kind === "direct" ? extractDigits(String(record.number ?? "")) : undefined;
+    if (phoneDigits) aliases.add(`${phoneDigits}@c.us`);
+    upsertPeer(
+      contactId,
+      {
+        kind: parsed?.kind ?? "unknown",
+        displayName: extractName(record),
+        verifiedName: String(record.verifiedName ?? "").trim() || undefined,
+        phoneE164: parsed?.phoneE164 ?? phoneDigits,
+        lid: parsed?.lid,
+      },
+      aliases,
+    );
+  }
+
+  const chats = await client.listChats(account.session, CHAT_SYNC_LIMIT, 0).catch((err) => {
+    getWahaV2Logger().warn(
+      `waha-v2: identity chat sync failed for session "${account.session}": ${String(err)}`,
+    );
+    return [];
+  });
+
+  if (Array.isArray(chats)) {
+    for (const chat of chats) {
+      if (!chat || typeof chat !== "object") continue;
+      const record = chat as Record<string, unknown>;
+      const chatId = normalizeRawId(record.id ?? record.chatId);
+      if (!chatId) continue;
+      const parsedChat = parseJid(chatId);
+      const recentMessages = await client
+        .getChatMessages(account.session, chatId, RECENT_MESSAGE_LIMIT, false)
+        .catch((err) => {
+          getWahaV2Logger().warn(
+            `waha-v2: identity message sync failed for ${chatId} (${account.session}): ${String(err)}`,
+          );
+          return [];
+        });
+
+      const summaries = summarizeRecentMessages(recentMessages, selfAliasSet);
+      const aliasSet = new Set<string>();
+      addAlias(aliasSet, chatId);
+
+      let resolvedPhone = parsedChat?.phoneE164;
+      let resolvedLid = parsedChat?.lid;
+      if (parsedChat?.lid && lidMappings.has(parsedChat.lid)) {
+        resolvedPhone = mergePreferredPhone(resolvedPhone, lidMappings.get(parsedChat.lid));
+      }
+      if (parsedChat?.kind === "direct" && parsedChat.phoneE164) {
+        const directChatId = `${parsedChat.phoneE164}@c.us`;
+        if (phoneToLid.has(directChatId)) {
+          resolvedLid = mergePreferredText(resolvedLid, phoneToLid.get(directChatId));
+        }
+      }
+      if (summaries.length > 0) {
+        for (const message of summaries) {
+          const counterpartId = message.direction === "out" ? message.to : message.from;
+          const counterpartRaw = normalizeRawId(counterpartId);
+          if (
+            counterpartRaw &&
+            !selfAliasSet.has(counterpartRaw) &&
+            !selfAliasSet.has(parseJid(counterpartRaw)?.bare ?? "")
+          ) {
+            addAlias(aliasSet, counterpartRaw);
+          }
+          const parsedCounterpart = parseJid(counterpartId);
+          resolvedPhone = mergePreferredPhone(resolvedPhone, parsedCounterpart?.phoneE164);
+          resolvedLid = mergePreferredText(resolvedLid, parsedCounterpart?.lid);
+          if (parsedCounterpart?.lid && lidMappings.has(parsedCounterpart.lid)) {
+            resolvedPhone = mergePreferredPhone(resolvedPhone, lidMappings.get(parsedCounterpart.lid));
+          }
+          if (parsedCounterpart?.kind === "direct" && parsedCounterpart.phoneE164) {
+            const directCounterpartId = `${parsedCounterpart.phoneE164}@c.us`;
+            if (phoneToLid.has(directCounterpartId)) {
+              resolvedLid = mergePreferredText(resolvedLid, phoneToLid.get(directCounterpartId));
+            }
+          }
+        }
+      }
+
+      upsertPeer(
+        chatId,
+        {
+          kind: record.isGroup === true ? "group" : (parsedChat?.kind ?? "unknown"),
+          displayName: extractName(record),
+          phoneE164: resolvedPhone,
+          lid: resolvedLid,
+          recentMessages: summaries,
+          lastMessageAt: summaries[0]?.timestamp,
+        },
+        aliasSet,
+      );
+    }
+  }
+
+  const index: WahaV2IdentityIndex = {
+    version: IDENTITY_INDEX_VERSION,
+    accountId: account.accountId,
+    session: account.session,
+    refreshedAt: new Date().toISOString(),
+    stateDir: resolveStateDir(),
+    self:
+      selfAliasSet.size > 0 || selfPhoneE164 || selfDisplayNames.length > 0
+        ? {
+            displayName: selfDisplayNames[0],
+            phoneE164: selfPhoneE164,
+            aliases: Array.from(selfAliasSet).sort(),
+          }
+        : undefined,
+    peers: Object.fromEntries(Array.from(peers.entries()).sort(([a], [b]) => a.localeCompare(b))),
+    lookup: Object.fromEntries(Array.from(lookup.entries()).sort(([a], [b]) => a.localeCompare(b))),
+    canonical: Object.fromEntries(
+      Array.from(canonical.entries()).sort(([a], [b]) => a.localeCompare(b)),
+    ),
+    lidMappings: Object.fromEntries(
+      Array.from(lidMappings.entries()).sort(([a], [b]) => a.localeCompare(b)),
+    ),
+  };
+  return index;
+}
+
+async function loadIdentityIndex(account: ResolvedWahaV2Account): Promise<WahaV2IdentityIndex | undefined> {
+  const key = cacheKey(account);
+  const cached = identityCache.get(key);
+  if (cached) return cached;
+
+  try {
+    const raw = await readFile(resolveIdentityIndexPath(account), "utf8");
+    const parsed = JSON.parse(raw) as Partial<WahaV2IdentityIndex>;
+    const hydrated = {
+      version: parsed.version ?? IDENTITY_INDEX_VERSION,
+      accountId: parsed.accountId ?? account.accountId,
+      session: parsed.session ?? account.session,
+      refreshedAt: parsed.refreshedAt ?? new Date(0).toISOString(),
+      stateDir: parsed.stateDir ?? resolveStateDir(),
+      self: parsed.self,
+      peers: parsed.peers ?? {},
+      lookup: parsed.lookup ?? {},
+      canonical: parsed.canonical ?? {},
+      lidMappings: parsed.lidMappings ?? {},
+    } satisfies WahaV2IdentityIndex;
+    identityCache.set(key, hydrated);
+    return hydrated;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function warmWahaV2IdentityIndex(
+  client: WahaV2Client,
+  account: ResolvedWahaV2Account,
+  reason: string,
+): Promise<WahaV2IdentityIndex> {
+  const key = cacheKey(account);
+  const existing = warmInFlight.get(key);
+  if (existing) return existing;
+
+  const task = (async () => {
+    getWahaV2Logger().info(
+      `waha-v2: identity warmup started for account "${account.accountId}" session="${account.session}" reason=${reason}`,
+    );
+    const index = await buildIdentityIndex(client, account);
+    await writeIdentityIndex(index);
+    identityCache.set(key, index);
+    getWahaV2Logger().info(
+      `waha-v2: identity warmup completed for account "${account.accountId}" session="${account.session}" peers=${Object.keys(index.peers).length}`,
+    );
+    return index;
+  })()
+    .catch((err) => {
+      getWahaV2Logger().warn(
+        `waha-v2: identity warmup failed for account "${account.accountId}" session="${account.session}": ${String(err)}`,
+      );
+      throw err;
+    })
+    .finally(() => {
+      warmInFlight.delete(key);
+    });
+
+  warmInFlight.set(key, task);
+  return task;
+}
+
+export async function resolveWahaV2Identity(
+  account: ResolvedWahaV2Account,
+  params: { chatId?: string; senderId?: string },
+): Promise<WahaV2ResolvedIdentity> {
+  const index = await loadIdentityIndex(account);
+  const path = resolveIdentityIndexPath(account);
+  if (!index) return { indexPath: path };
+
+  const chatId = normalizeRawId(params.chatId);
+  const senderId = normalizeRawId(params.senderId);
+  const resolvePeer = (rawValue?: string): WahaV2IdentityPeerRecord | undefined => {
+    const parsed = parseJid(rawValue);
+    if (!parsed) return undefined;
+    const candidates = [parsed.raw, parsed.bare];
+    if (parsed.phoneE164) candidates.push(`${parsed.phoneE164}@c.us`);
+    for (const candidate of candidates) {
+      const chatKey = index.lookup[candidate];
+      if (chatKey && index.peers[chatKey]) return index.peers[chatKey];
+    }
+    return undefined;
+  };
+  const resolveCanonical = (rawValue?: string): string | undefined => {
+    const parsed = parseJid(rawValue);
+    if (!parsed) return undefined;
+    const candidates = [parsed.raw, parsed.bare];
+    if (parsed.phoneE164) candidates.push(`${parsed.phoneE164}@c.us`);
+    for (const candidate of candidates) {
+      const canonicalId = index.canonical[candidate];
+      if (canonicalId) return canonicalId;
+    }
+    if (parsed.kind === "direct" && parsed.phoneE164) return `${parsed.phoneE164}@c.us`;
+    if (parsed.kind === "group") return parsed.raw;
+    return undefined;
+  };
+
+  return {
+    chat: resolvePeer(chatId),
+    sender: resolvePeer(senderId),
+    canonicalChatId: resolveCanonical(chatId),
+    canonicalSenderId: resolveCanonical(senderId),
+    indexPath: path,
+  };
+}
+
+export function buildWahaV2IdentityContext(params: {
+  chatId?: string;
+  senderId?: string;
+  isGroup: boolean;
+  resolved: WahaV2ResolvedIdentity;
+}): string | undefined {
+  const lines: string[] = [];
+  const chatId = normalizeRawId(params.chatId);
+  const senderId = normalizeRawId(params.senderId);
+  const chat = params.resolved.chat;
+  const sender = params.resolved.sender;
+
+  if (!chatId && !senderId && !chat && !sender) return undefined;
+
+  lines.push("[WHATSAPP IDENTITY]");
+  if (chatId) lines.push(`ChatId: ${chatId}`);
+  if (params.resolved.canonicalChatId) lines.push(`CanonicalChatId: ${params.resolved.canonicalChatId}`);
+  if (chat?.displayName) lines.push(`ChatName: ${chat.displayName}`);
+  if (params.isGroup) {
+    if (senderId) lines.push(`SenderId: ${senderId}`);
+    if (params.resolved.canonicalSenderId) {
+      lines.push(`CanonicalSenderId: ${params.resolved.canonicalSenderId}`);
+    }
+    if (sender?.displayName) lines.push(`SenderName: ${sender.displayName}`);
+    if (sender?.phoneE164) lines.push(`SenderPhone: ${sender.phoneE164}`);
+  } else {
+    if (senderId) lines.push(`PeerId: ${senderId}`);
+    if (params.resolved.canonicalSenderId) {
+      lines.push(`CanonicalPeerId: ${params.resolved.canonicalSenderId}`);
+    }
+    if ((sender ?? chat)?.displayName) lines.push(`PeerName: ${(sender ?? chat)?.displayName}`);
+    if ((sender ?? chat)?.phoneE164) lines.push(`PeerPhone: ${(sender ?? chat)?.phoneE164}`);
+  }
+  if ((sender ?? chat)?.lid) lines.push(`PeerLid: ${(sender ?? chat)?.lid}`);
+  const recent = chat?.recentMessages ?? [];
+  if (recent.length > 0) {
+    lines.push("RecentMessages:");
+    for (const message of recent.slice(0, RECENT_MESSAGE_LIMIT)) {
+      lines.push(formatRecentMessageForAgent(message));
+    }
+  }
+  lines.push(`IdentityIndex: ${params.resolved.indexPath}`);
+  return `${lines.join("\n")}\n\n`;
+}

package/src/webhook.ts

@@ -7,6 +7,7 @@ import { readJsonBodyWithLimit, sleep } from "openclaw/plugin-sdk";
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import { resolveWahaV2Account, resolveWahaV2AccountBySession } from "./accounts.js";
 import { calcTypingDelayMs, chunkWahaMessage } from "./deliver.js";
+import { buildWahaV2IdentityContext, resolveWahaV2Identity } from "./identity.js";
 import { getWahaV2Logger, getWahaV2Runtime, requireWahaV2Client } from "./runtime.js";
 import {
   WAHA_V2_CHANNEL_ID,
@@ -280,10 +281,9 @@ async function applyLabelDirectivesToChat(
   );
 }
 
-/** Normalize E.164-ish numbers to `<digits>@c.us`. */
+/** Preserve WA JIDs as-is while normalizing case/whitespace. */
 function normalizeSenderId(raw: string): string {
-  if (raw.includes("@")) return raw;
-  return `${raw.replace(/\D+/g, "")}@c.us`;
+  return String(raw ?? "").trim().toLowerCase();
 }
 
 function matchesOwnerPauseWord(text: string, words?: string[]): string | undefined {
@@ -533,10 +533,31 @@ async function processWahaV2EventImmediate(
   // Build a descriptive body when there's media but no caption text.
   const mediaLabel = mediaPath ? mediaTypeLabel(payload.type, mediaMime) : undefined;
   const bodyForAgent = text || (mediaLabel ? `[${mediaLabel}]` : "");
+  const resolvedIdentity = await resolveWahaV2Identity(account, { chatId, senderId }).catch((err) => {
+    getWahaV2Logger().warn(`waha-v2: identity resolution failed (${chatId}): ${String(err)}`);
+    return {
+      chat: undefined,
+      sender: undefined,
+      canonicalChatId: undefined,
+      canonicalSenderId: undefined,
+      indexPath: "unavailable",
+    };
+  });
+  const canonicalChatId =
+    isGroup ? chatId : (resolvedIdentity.canonicalChatId ?? resolvedIdentity.canonicalSenderId ?? chatId);
+  const canonicalSenderId = isGroup
+    ? (resolvedIdentity.canonicalSenderId ?? senderId)
+    : (resolvedIdentity.canonicalSenderId ?? resolvedIdentity.canonicalChatId ?? senderId);
+  const identityPrefix = buildWahaV2IdentityContext({
+    chatId,
+    senderId,
+    isGroup,
+    resolved: resolvedIdentity,
+  });
   const policyPrefix = policyInstruction
     ? `[CHAT POLICY]\nLabels: ${labelSummary}\nInstruction: ${policyInstruction}\n\n`
     : "";
-  const bodyForAgentWithPolicy = `${policyPrefix}${bodyForAgent}`.trim();
+  const bodyForAgentWithPolicy = `${identityPrefix ?? ""}${policyPrefix}${bodyForAgent}`.trim();
 
   // If we have both caption text and media, surface both in Body.
   const combinedBody = text && mediaLabel ? `${text}\n[${mediaLabel}]` : bodyForAgent;
@@ -545,7 +566,7 @@ async function processWahaV2EventImmediate(
     cfg,
     channel: WAHA_V2_CHANNEL_ID,
     accountId: account.accountId,
-    peer: { kind: isGroup ? "group" : "direct", id: chatId },
+    peer: { kind: isGroup ? "group" : "direct", id: canonicalChatId },
   });
 
   const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
@@ -557,14 +578,23 @@ async function processWahaV2EventImmediate(
     BodyForAgent: bodyForAgentWithPolicy,
     RawBody: text,
     CommandBody: text,
-    From: `${WAHA_V2_CHANNEL_ID}:${senderId}`,
+    From: `${WAHA_V2_CHANNEL_ID}:${canonicalSenderId}`,
     To: `${WAHA_V2_CHANNEL_ID}:${account.session}`,
     SessionKey: route.sessionKey,
     AccountId: route.accountId,
     ChatType: isGroup ? ("group" as const) : ("direct" as const),
     Provider: WAHA_V2_CHANNEL_ID,
     Surface: WAHA_V2_CHANNEL_ID,
-    SenderId: senderId,
+    SenderId: canonicalSenderId,
+    WahaChatId: chatId,
+    WahaSenderId: senderId,
+    WahaCanonicalChatId: canonicalChatId,
+    WahaCanonicalSenderId: canonicalSenderId,
+    WahaChatName: resolvedIdentity.chat?.displayName,
+    WahaChatPhone: resolvedIdentity.chat?.phoneE164,
+    WahaSenderName: resolvedIdentity.sender?.displayName ?? resolvedIdentity.chat?.displayName,
+    WahaSenderPhone: resolvedIdentity.sender?.phoneE164 ?? resolvedIdentity.chat?.phoneE164,
+    WahaIdentityIndexPath: resolvedIdentity.indexPath,
     MessageSid: payload.id,
     Timestamp: payload.timestamp ? payload.timestamp * 1000 : Date.now(),
     // Media fields — consumed by the agent framework to send the file to the AI.