from __future__ import annotations
"""
Feishu/Lark drive document comment handling.

Processes ``drive.notice.comment_add_v1`` events and interacts with the
Drive v2 comment reaction API.  Kept in a separate module so that the
main ``feishu.py`` adapter does not grow further and comment-related
logic can evolve independently.

Flow:
  1. Parse event -> extract file_token, comment_id, reply_id, etc.
  2. Add OK reaction
  3. Parallel fetch: doc meta + comment details (batch_query)
  4. Branch on is_whole:
       Whole -> list whole comments timeline
       Local -> list comment thread replies
  5. Build prompt (local or whole)
  6. Create AIAgent with feishu_doc + feishu_drive tools -> agent generates reply
  7. Route reply:
       Whole -> add_whole_comment
       Local -> reply_to_comment (fallback to add_whole_comment on 1069302)
"""


import asyncio
import json
import logging
from typing import Any, Dict, List, Optional, Tuple

logger = logging.getLogger(__name__)

# ---------------------------------------------------------------------------
# Lark SDK helpers (lazy-imported)
# ---------------------------------------------------------------------------


def _build_request(method: str, uri: str, paths=None, queries=None, body=None):
    """Build a lark_oapi BaseRequest."""
    from lark_oapi import AccessTokenType
    from lark_oapi.core.enum import HttpMethod
    from lark_oapi.core.model.base_request import BaseRequest

    http_method = HttpMethod.GET if method == "GET" else HttpMethod.POST

    builder = (
        BaseRequest.builder()
        .http_method(http_method)
        .uri(uri)
        .token_types({AccessTokenType.TENANT})
    )
    if paths:
        builder = builder.paths(paths)
    if queries:
        builder = builder.queries(queries)
    if body is not None:
        builder = builder.body(body)
    return builder.build()


async def _exec_request(client, method, uri, paths=None, queries=None, body=None):
    """Execute a lark API request and return (code, msg, data_dict)."""
    logger.info("[Feishu-Comment] API >>> %s %s paths=%s queries=%s body=%s",
                 method, uri, paths, queries,
                 json.dumps(body, ensure_ascii=False)[:500] if body else None)
    request = _build_request(method, uri, paths, queries, body)
    response = await asyncio.to_thread(client.request, request)

    code = getattr(response, "code", None)
    msg = getattr(response, "msg", "")

    data: dict = {}
    raw = getattr(response, "raw", None)
    if raw and hasattr(raw, "content"):
        try:
            body_json = json.loads(raw.content)
            data = body_json.get("data", {})
        except (json.JSONDecodeError, AttributeError):
            pass
    if not data:
        resp_data = getattr(response, "data", None)
        if isinstance(resp_data, dict):
            data = resp_data
        elif resp_data and hasattr(resp_data, "__dict__"):
            data = vars(resp_data)

    logger.info("[Feishu-Comment] API <<< %s %s code=%s msg=%s data_keys=%s",
                 method, uri, code, msg, list(data.keys()) if data else "empty")
    if code != 0:
        # Log raw response for debugging failed API calls
        raw = getattr(response, "raw", None)
        raw_content = ""
        if raw and hasattr(raw, "content"):
            raw_content = raw.content[:500] if isinstance(raw.content, (str, bytes)) else str(raw.content)[:500]
        logger.warning("[Feishu-Comment] API FAIL raw response: %s", raw_content)
    return code, msg, data


# ---------------------------------------------------------------------------
# Event parsing
# ---------------------------------------------------------------------------


def parse_drive_comment_event(data: Any) -> Optional[Dict[str, Any]]:
    """Extract structured fields from a ``drive.notice.comment_add_v1`` payload.

    *data* may be a ``CustomizedEvent`` (WebSocket) whose ``.event`` is a dict,
    or a ``SimpleNamespace`` (Webhook) built from the full JSON body.

    Returns a flat dict with the relevant fields, or ``None`` when the
    payload is malformed.
    """
    logger.debug("[Feishu-Comment] parse_drive_comment_event: data type=%s", type(data).__name__)
    event = getattr(data, "event", None)
    if event is None:
        logger.debug("[Feishu-Comment] parse_drive_comment_event: no .event attribute, returning None")
        return None

    evt: dict = event if isinstance(event, dict) else (
        vars(event) if hasattr(event, "__dict__") else {}
    )
    logger.debug("[Feishu-Comment] parse_drive_comment_event: evt keys=%s", list(evt.keys()))

    notice_meta = evt.get("notice_meta") or {}
    if not isinstance(notice_meta, dict):
        notice_meta = vars(notice_meta) if hasattr(notice_meta, "__dict__") else {}

    from_user = notice_meta.get("from_user_id") or {}
    if not isinstance(from_user, dict):
        from_user = vars(from_user) if hasattr(from_user, "__dict__") else {}

    to_user = notice_meta.get("to_user_id") or {}
    if not isinstance(to_user, dict):
        to_user = vars(to_user) if hasattr(to_user, "__dict__") else {}

    return {
        "event_id": str(evt.get("event_id") or ""),
        "comment_id": str(evt.get("comment_id") or ""),
        "reply_id": str(evt.get("reply_id") or ""),
        "is_mentioned": bool(evt.get("is_mentioned")),
        "timestamp": str(evt.get("timestamp") or ""),
        "file_token": str(notice_meta.get("file_token") or ""),
        "file_type": str(notice_meta.get("file_type") or ""),
        "notice_type": str(notice_meta.get("notice_type") or ""),
        "from_open_id": str(from_user.get("open_id") or ""),
        "to_open_id": str(to_user.get("open_id") or ""),
    }


# ---------------------------------------------------------------------------
# Comment reaction API
# ---------------------------------------------------------------------------

_REACTION_URI = "/open-apis/drive/v2/files/:file_token/comments/reaction"


async def add_comment_reaction(
    client: Any,
    *,
    file_token: str,
    file_type: str,
    reply_id: str,
    reaction_type: str = "OK",
) -> bool:
    """Add an emoji reaction to a document comment reply.

    Uses the Drive v2 ``update_reaction`` endpoint::

        POST /open-apis/drive/v2/files/{file_token}/comments/reaction?file_type=...

    Returns ``True`` on success, ``False`` on failure (errors are logged).
    """
    try:
        from lark_oapi import AccessTokenType  # noqa: F401
    except ImportError:
        logger.error("[Feishu-Comment] lark_oapi not available")
        return False

    body = {
        "action": "add",
        "reply_id": reply_id,
        "reaction_type": reaction_type,
    }

    code, msg, _ = await _exec_request(
        client, "POST", _REACTION_URI,
        paths={"file_token": file_token},
        queries=[("file_type", file_type)],
        body=body,
    )

    succeeded = code == 0
    if succeeded:
        logger.info(
            "[Feishu-Comment] Reaction '%s' added: file=%s:%s reply=%s",
            reaction_type, file_type, file_token, reply_id,
        )
    else:
        logger.warning(
            "[Feishu-Comment] Reaction API failed: code=%s msg=%s "
            "file=%s:%s reply=%s",
            code, msg, file_type, file_token, reply_id,
        )
    return succeeded


async def delete_comment_reaction(
    client: Any,
    *,
    file_token: str,
    file_type: str,
    reply_id: str,
    reaction_type: str = "OK",
) -> bool:
    """Remove an emoji reaction from a document comment reply.

    Best-effort — errors are logged but not raised.
    """
    body = {
        "action": "delete",
        "reply_id": reply_id,
        "reaction_type": reaction_type,
    }

    code, msg, _ = await _exec_request(
        client, "POST", _REACTION_URI,
        paths={"file_token": file_token},
        queries=[("file_type", file_type)],
        body=body,
    )

    succeeded = code == 0
    if succeeded:
        logger.info(
            "[Feishu-Comment] Reaction '%s' deleted: file=%s:%s reply=%s",
            reaction_type, file_type, file_token, reply_id,
        )
    else:
        logger.warning(
            "[Feishu-Comment] Reaction API failed: code=%s msg=%s "
            "file=%s:%s reply=%s",
            code, msg, file_type, file_token, reply_id,
        )
    return succeeded


# ---------------------------------------------------------------------------
# API call layer
# ---------------------------------------------------------------------------

_BATCH_QUERY_META_URI = "/open-apis/drive/v1/metas/batch_query"
_BATCH_QUERY_COMMENT_URI = "/open-apis/drive/v1/files/:file_token/comments/batch_query"
_LIST_COMMENTS_URI = "/open-apis/drive/v1/files/:file_token/comments"
_LIST_REPLIES_URI = "/open-apis/drive/v1/files/:file_token/comments/:comment_id/replies"
_REPLY_COMMENT_URI = "/open-apis/drive/v1/files/:file_token/comments/:comment_id/replies"
_ADD_COMMENT_URI = "/open-apis/drive/v1/files/:file_token/new_comments"


async def query_document_meta(
    client: Any, file_token: str, file_type: str,
) -> Dict[str, Any]:
    """Fetch document title and URL via batch_query meta API.

    Returns ``{"title": "...", "url": "...", "doc_type": "..."}`` or empty dict.
    """
    body = {
        "request_docs": [{"doc_token": file_token, "doc_type": file_type}],
        "with_url": True,
    }
    logger.debug("[Feishu-Comment] query_document_meta: file_token=%s file_type=%s", file_token, file_type)
    code, msg, data = await _exec_request(
        client, "POST", _BATCH_QUERY_META_URI, body=body,
    )
    if code != 0:
        logger.warning("[Feishu-Comment] Meta batch_query failed: code=%s msg=%s", code, msg)
        return {}

    metas = data.get("metas", [])
    logger.debug("[Feishu-Comment] query_document_meta: raw metas type=%s value=%s",
                 type(metas).__name__, str(metas)[:300])
    if not metas:
        # Try alternate response shape: metas may be a dict keyed by token
        if isinstance(data.get("metas"), dict):
            meta = data["metas"].get(file_token, {})
        else:
            logger.debug("[Feishu-Comment] query_document_meta: no metas found")
            return {}
    else:
        meta = metas[0] if isinstance(metas, list) else {}

    result = {
        "title": meta.get("title", ""),
        "url": meta.get("url", ""),
        "doc_type": meta.get("doc_type", file_type),
    }
    logger.info("[Feishu-Comment] query_document_meta: title=%s url=%s",
                result["title"], result["url"][:80] if result["url"] else "")
    return result


_COMMENT_RETRY_LIMIT = 6
_COMMENT_RETRY_DELAY_S = 1.0


async def batch_query_comment(
    client: Any, file_token: str, file_type: str, comment_id: str,
) -> Dict[str, Any]:
    """Fetch comment details via batch_query comment API.

    Retries up to 6 times on failure (handles eventual consistency).

    Returns the comment dict with fields like ``is_whole``, ``quote``,
    ``reply_list``, etc.  Empty dict on failure.
    """
    logger.debug("[Feishu-Comment] batch_query_comment: file_token=%s comment_id=%s", file_token, comment_id)

    for attempt in range(_COMMENT_RETRY_LIMIT):
        code, msg, data = await _exec_request(
            client, "POST", _BATCH_QUERY_COMMENT_URI,
            paths={"file_token": file_token},
            queries=[
                ("file_type", file_type),
                ("user_id_type", "open_id"),
            ],
            body={"comment_ids": [comment_id]},
        )
        if code == 0:
            break
        if attempt < _COMMENT_RETRY_LIMIT - 1:
            logger.info(
                "[Feishu-Comment] batch_query_comment retry %d/%d: code=%s msg=%s",
                attempt + 1, _COMMENT_RETRY_LIMIT, code, msg,
            )
            await asyncio.sleep(_COMMENT_RETRY_DELAY_S)
        else:
            logger.warning(
                "[Feishu-Comment] batch_query_comment failed after %d attempts: code=%s msg=%s",
                _COMMENT_RETRY_LIMIT, code, msg,
            )
            return {}

    # Response: {"items": [{"comment_id": "...", ...}]}
    items = data.get("items", [])
    logger.debug("[Feishu-Comment] batch_query_comment: got %d items", len(items) if isinstance(items, list) else 0)
    if items and isinstance(items, list):
        item = items[0]
        logger.info("[Feishu-Comment] batch_query_comment: is_whole=%s quote=%s reply_count=%s",
                    item.get("is_whole"),
                    (item.get("quote", "") or "")[:60],
                    len(item.get("reply_list", {}).get("replies", [])) if isinstance(item.get("reply_list"), dict) else "?")
        return item
    logger.warning("[Feishu-Comment] batch_query_comment: empty items, raw data keys=%s", list(data.keys()))
    return {}


async def list_whole_comments(
    client: Any, file_token: str, file_type: str,
) -> List[Dict[str, Any]]:
    """List all whole-document comments (paginated, up to 500)."""
    logger.debug("[Feishu-Comment] list_whole_comments: file_token=%s", file_token)
    all_comments: List[Dict[str, Any]] = []
    page_token = ""

    for _ in range(5):  # max 5 pages
        queries = [
            ("file_type", file_type),
            ("is_whole", "true"),
            ("page_size", "100"),
            ("user_id_type", "open_id"),
        ]
        if page_token:
            queries.append(("page_token", page_token))

        code, msg, data = await _exec_request(
            client, "GET", _LIST_COMMENTS_URI,
            paths={"file_token": file_token},
            queries=queries,
        )
        if code != 0:
            logger.warning("[Feishu-Comment] List whole comments failed: code=%s msg=%s", code, msg)
            break

        items = data.get("items", [])
        if isinstance(items, list):
            all_comments.extend(items)
            logger.debug("[Feishu-Comment] list_whole_comments: page got %d items, total=%d",
                         len(items), len(all_comments))

        if not data.get("has_more"):
            break
        page_token = data.get("page_token", "")
        if not page_token:
            break

    logger.info("[Feishu-Comment] list_whole_comments: total %d whole comments fetched", len(all_comments))
    return all_comments


async def list_comment_replies(
    client: Any, file_token: str, file_type: str, comment_id: str,
    *, expect_reply_id: str = "",
) -> List[Dict[str, Any]]:
    """List all replies in a comment thread (paginated, up to 500).

    If *expect_reply_id* is set and not found in the first fetch,
    retries up to 6 times (handles eventual consistency).
    """
    logger.debug("[Feishu-Comment] list_comment_replies: file_token=%s comment_id=%s", file_token, comment_id)

    for attempt in range(_COMMENT_RETRY_LIMIT):
        all_replies: List[Dict[str, Any]] = []
        page_token = ""
        fetch_ok = True

        for _ in range(5):  # max 5 pages
            queries = [
                ("file_type", file_type),
                ("page_size", "100"),
                ("user_id_type", "open_id"),
            ]
            if page_token:
                queries.append(("page_token", page_token))

            code, msg, data = await _exec_request(
                client, "GET", _LIST_REPLIES_URI,
                paths={"file_token": file_token, "comment_id": comment_id},
                queries=queries,
            )
            if code != 0:
                logger.warning("[Feishu-Comment] List replies failed: code=%s msg=%s", code, msg)
                fetch_ok = False
                break

            items = data.get("items", [])
            if isinstance(items, list):
                all_replies.extend(items)

            if not data.get("has_more"):
                break
            page_token = data.get("page_token", "")
            if not page_token:
                break

        # If we don't need a specific reply, or we found it, return
        if not expect_reply_id or not fetch_ok:
            break
        found = any(r.get("reply_id") == expect_reply_id for r in all_replies)
        if found:
            break
        if attempt < _COMMENT_RETRY_LIMIT - 1:
            logger.info(
                "[Feishu-Comment] list_comment_replies: reply_id=%s not found, retry %d/%d",
                expect_reply_id, attempt + 1, _COMMENT_RETRY_LIMIT,
            )
            await asyncio.sleep(_COMMENT_RETRY_DELAY_S)
        else:
            logger.warning(
                "[Feishu-Comment] list_comment_replies: reply_id=%s not found after %d attempts",
                expect_reply_id, _COMMENT_RETRY_LIMIT,
            )

    logger.info("[Feishu-Comment] list_comment_replies: total %d replies fetched", len(all_replies))
    return all_replies


def _sanitize_comment_text(text: str) -> str:
    """Escape characters not allowed in Feishu comment text_run content."""
    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")


async def reply_to_comment(
    client: Any, file_token: str, file_type: str, comment_id: str, text: str,
) -> Tuple[bool, int]:
    """Post a reply to a local comment thread.

    Returns ``(success, code)``.
    """
    text = _sanitize_comment_text(text)
    logger.info("[Feishu-Comment] reply_to_comment: comment_id=%s text=%s",
                comment_id, text[:100])
    body = {
        "content": {
            "elements": [
                {"type": "text_run", "text_run": {"text": text}},
            ]
        }
    }

    code, msg, _ = await _exec_request(
        client, "POST", _REPLY_COMMENT_URI,
        paths={"file_token": file_token, "comment_id": comment_id},
        queries=[("file_type", file_type)],
        body=body,
    )
    if code != 0:
        logger.warning(
            "[Feishu-Comment] reply_to_comment FAILED: code=%s msg=%s comment_id=%s",
            code, msg, comment_id,
        )
    else:
        logger.info("[Feishu-Comment] reply_to_comment OK: comment_id=%s", comment_id)
    return code == 0, code


async def add_whole_comment(
    client: Any, file_token: str, file_type: str, text: str,
) -> bool:
    """Add a new whole-document comment.

    Returns ``True`` on success.
    """
    text = _sanitize_comment_text(text)
    logger.info("[Feishu-Comment] add_whole_comment: file_token=%s text=%s",
                file_token, text[:100])
    body = {
        "file_type": file_type,
        "reply_elements": [
            {"type": "text", "text": text},
        ],
    }

    code, msg, _ = await _exec_request(
        client, "POST", _ADD_COMMENT_URI,
        paths={"file_token": file_token},
        body=body,
    )
    if code != 0:
        logger.warning("[Feishu-Comment] add_whole_comment FAILED: code=%s msg=%s", code, msg)
    else:
        logger.info("[Feishu-Comment] add_whole_comment OK")
    return code == 0


_REPLY_CHUNK_SIZE = 4000


def _chunk_text(text: str, limit: int = _REPLY_CHUNK_SIZE) -> List[str]:
    """Split text into chunks for delivery, preferring line breaks."""
    if len(text) <= limit:
        return [text]
    chunks = []
    while text:
        if len(text) <= limit:
            chunks.append(text)
            break
        # Find last newline within limit
        cut = text.rfind("\n", 0, limit)
        if cut <= 0:
            cut = limit
        chunks.append(text[:cut])
        text = text[cut:].lstrip("\n")
    return chunks


async def deliver_comment_reply(
    client: Any,
    file_token: str,
    file_type: str,
    comment_id: str,
    text: str,
    is_whole: bool,
) -> bool:
    """Route agent reply to the correct API, chunking long text.

    - Whole comment -> add_whole_comment
    - Local comment -> reply_to_comment, fallback to add_whole_comment on 1069302
    """
    chunks = _chunk_text(text)
    logger.info("[Feishu-Comment] deliver_comment_reply: is_whole=%s comment_id=%s text_len=%d chunks=%d",
                is_whole, comment_id, len(text), len(chunks))

    all_ok = True
    for i, chunk in enumerate(chunks):
        if len(chunks) > 1:
            logger.info("[Feishu-Comment] deliver_comment_reply: sending chunk %d/%d (%d chars)",
                        i + 1, len(chunks), len(chunk))

        if is_whole:
            ok = await add_whole_comment(client, file_token, file_type, chunk)
        else:
            success, code = await reply_to_comment(client, file_token, file_type, comment_id, chunk)
            if success:
                ok = True
            elif code == 1069302:
                logger.info("[Feishu-Comment] Reply not allowed (1069302), falling back to add_whole_comment")
                ok = await add_whole_comment(client, file_token, file_type, chunk)
                is_whole = True  # subsequent chunks also use add_comment
            else:
                ok = False

        if not ok:
            all_ok = False
            break

    return all_ok


# ---------------------------------------------------------------------------
# Comment content extraction helpers
# ---------------------------------------------------------------------------


def _extract_reply_text(reply: Dict[str, Any]) -> str:
    """Extract plain text from a comment reply's content structure."""
    content = reply.get("content", {})
    if isinstance(content, str):
        try:
            content = json.loads(content)
        except (json.JSONDecodeError, TypeError):
            return content

    elements = content.get("elements", [])
    parts = []
    for elem in elements:
        if elem.get("type") == "text_run":
            text_run = elem.get("text_run", {})
            parts.append(text_run.get("text", ""))
        elif elem.get("type") == "docs_link":
            docs_link = elem.get("docs_link", {})
            parts.append(docs_link.get("url", ""))
        elif elem.get("type") == "person":
            person = elem.get("person", {})
            parts.append(f"@{person.get('user_id', 'unknown')}")
    return "".join(parts)


def _get_reply_user_id(reply: Dict[str, Any]) -> str:
    """Extract user_id from a reply dict."""
    user_id = reply.get("user_id", "")
    if isinstance(user_id, dict):
        return user_id.get("open_id", "") or user_id.get("user_id", "")
    return str(user_id)


def _extract_semantic_text(reply: Dict[str, Any], self_open_id: str = "") -> str:
    """Extract semantic text from a reply, stripping self @mentions and extra whitespace."""
    content = reply.get("content", {})
    if isinstance(content, str):
        try:
            content = json.loads(content)
        except (json.JSONDecodeError, TypeError):
            return content

    elements = content.get("elements", [])
    parts = []
    for elem in elements:
        if elem.get("type") == "person":
            person = elem.get("person", {})
            uid = person.get("user_id", "")
            # Skip self @mention (it's routing, not content)
            if self_open_id and uid == self_open_id:
                continue
            parts.append(f"@{uid}")
        elif elem.get("type") == "text_run":
            text_run = elem.get("text_run", {})
            parts.append(text_run.get("text", ""))
        elif elem.get("type") == "docs_link":
            docs_link = elem.get("docs_link", {})
            parts.append(docs_link.get("url", ""))
    return " ".join("".join(parts).split()).strip()


# ---------------------------------------------------------------------------
# Document link parsing and wiki resolution
# ---------------------------------------------------------------------------

import re as _re

# Matches feishu/lark document URLs and extracts doc_type + token
_FEISHU_DOC_URL_RE = _re.compile(
    r"(?:feishu\.cn|larkoffice\.com|larksuite\.com|lark\.suite\.com)"
    r"/(?P<doc_type>wiki|doc|docx|sheet|sheets|slides|mindnote|bitable|base|file)"
    r"/(?P<token>[A-Za-z0-9_-]{10,40})"
)

_WIKI_GET_NODE_URI = "/open-apis/wiki/v2/spaces/get_node"


def _extract_docs_links(replies: List[Dict[str, Any]]) -> List[Dict[str, str]]:
    """Extract unique document links from a list of comment replies.

    Returns list of ``{"url": "...", "doc_type": "...", "token": "..."}`` dicts.
    """
    seen_tokens = set()
    links = []
    for reply in replies:
        content = reply.get("content", {})
        if isinstance(content, str):
            try:
                content = json.loads(content)
            except (json.JSONDecodeError, TypeError):
                continue
        for elem in content.get("elements", []):
            if elem.get("type") not in ("docs_link", "link"):
                continue
            link_data = elem.get("docs_link") or elem.get("link") or {}
            url = link_data.get("url", "")
            if not url:
                continue
            m = _FEISHU_DOC_URL_RE.search(url)
            if not m:
                continue
            doc_type = m.group("doc_type")
            token = m.group("token")
            if token in seen_tokens:
                continue
            seen_tokens.add(token)
            links.append({"url": url, "doc_type": doc_type, "token": token})
    return links


async def _reverse_lookup_wiki_token(
    client: Any, obj_type: str, obj_token: str,
) -> Optional[str]:
    """Reverse-lookup: given an obj_token, find its wiki node_token.

    Returns the wiki_token if the document belongs to a wiki space,
    or None if it doesn't or the API call fails.
    """
    code, msg, data = await _exec_request(
        client, "GET", _WIKI_GET_NODE_URI,
        queries=[("token", obj_token), ("obj_type", obj_type)],
    )
    if code == 0:
        node = data.get("node", {})
        wiki_token = node.get("node_token", "")
        return wiki_token if wiki_token else None
    # code != 0: either not a wiki doc or service error — log and return None
    logger.warning("[Feishu-Comment] Wiki reverse lookup failed: code=%s msg=%s obj=%s:%s", code, msg, obj_type, obj_token)
    return None


async def _resolve_wiki_nodes(
    client: Any,
    links: List[Dict[str, str]],
) -> List[Dict[str, str]]:
    """Resolve wiki links to their underlying document type and token.

    Mutates entries in *links* in-place: replaces ``doc_type`` and ``token``
    with the resolved values for wiki links.  Non-wiki links are unchanged.
    """
    wiki_links = [l for l in links if l["doc_type"] == "wiki"]
    if not wiki_links:
        return links

    for link in wiki_links:
        wiki_token = link["token"]
        code, msg, data = await _exec_request(
            client, "GET", _WIKI_GET_NODE_URI,
            queries=[("token", wiki_token)],
        )
        if code == 0:
            node = data.get("node", {})
            resolved_type = node.get("obj_type", "")
            resolved_token = node.get("obj_token", "")
            if resolved_type and resolved_token:
                logger.info(
                    "[Feishu-Comment] Wiki resolved: %s -> %s:%s",
                    wiki_token, resolved_type, resolved_token,
                )
                link["resolved_type"] = resolved_type
                link["resolved_token"] = resolved_token
            else:
                logger.warning("[Feishu-Comment] Wiki resolve returned empty: %s", wiki_token)
        else:
            logger.warning("[Feishu-Comment] Wiki resolve failed: code=%s msg=%s token=%s", code, msg, wiki_token)

    return links


def _format_referenced_docs(
    links: List[Dict[str, str]], current_file_token: str = "",
) -> str:
    """Format resolved document links for prompt embedding."""
    if not links:
        return ""
    lines = ["", "Referenced documents in comments:"]
    for link in links:
        rtype = link.get("resolved_type", link["doc_type"])
        rtoken = link.get("resolved_token", link["token"])
        is_current = rtoken == current_file_token
        suffix = " (same as current document)" if is_current else ""
        lines.append(f"- {rtype}:{rtoken}{suffix} ({link['url'][:80]})")
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Prompt construction
# ---------------------------------------------------------------------------

_PROMPT_TEXT_LIMIT = 220
_LOCAL_TIMELINE_LIMIT = 20
_WHOLE_TIMELINE_LIMIT = 12


def _truncate(text: str, limit: int = _PROMPT_TEXT_LIMIT) -> str:
    """Truncate text for prompt embedding."""
    if len(text) <= limit:
        return text
    return text[:limit] + "..."


def _select_local_timeline(
    timeline: List[Tuple[str, str, bool]],
    target_index: int,
) -> List[Tuple[str, str, bool]]:
    """Select up to _LOCAL_TIMELINE_LIMIT entries centered on target_index.

    Always keeps first, target, and last entries.
    """
    if len(timeline) <= _LOCAL_TIMELINE_LIMIT:
        return timeline
    n = len(timeline)
    selected = set()
    selected.add(0)                            # first
    selected.add(n - 1)                        # last
    if 0 <= target_index < n:
        selected.add(target_index)             # current
    # Expand outward from target
    budget = _LOCAL_TIMELINE_LIMIT - len(selected)
    lo, hi = target_index - 1, target_index + 1
    while budget > 0 and (lo >= 0 or hi < n):
        if lo >= 0 and lo not in selected:
            selected.add(lo)
            budget -= 1
        lo -= 1
        if budget > 0 and hi < n and hi not in selected:
            selected.add(hi)
            budget -= 1
        hi += 1
    return [timeline[i] for i in sorted(selected)]


def _select_whole_timeline(
    timeline: List[Tuple[str, str, bool]],
    current_index: int,
    nearest_self_index: int,
) -> List[Tuple[str, str, bool]]:
    """Select up to _WHOLE_TIMELINE_LIMIT entries for whole-doc comments.

    Prioritizes current entry and nearest self reply.
    """
    if len(timeline) <= _WHOLE_TIMELINE_LIMIT:
        return timeline
    n = len(timeline)
    selected = set()
    if 0 <= current_index < n:
        selected.add(current_index)
    if 0 <= nearest_self_index < n:
        selected.add(nearest_self_index)
    # Expand outward from current
    budget = _WHOLE_TIMELINE_LIMIT - len(selected)
    lo, hi = current_index - 1, current_index + 1
    while budget > 0 and (lo >= 0 or hi < n):
        if lo >= 0 and lo not in selected:
            selected.add(lo)
            budget -= 1
        lo -= 1
        if budget > 0 and hi < n and hi not in selected:
            selected.add(hi)
            budget -= 1
        hi += 1
    if not selected:
        # Fallback: take last N entries
        return timeline[-_WHOLE_TIMELINE_LIMIT:]
    return [timeline[i] for i in sorted(selected)]


_COMMON_INSTRUCTIONS = """
This is a Feishu document comment thread, not an IM chat.
Do NOT call feishu_drive_add_comment or feishu_drive_reply_comment yourself.
Your reply will be posted automatically. Just output the reply text.
Use the thread timeline above as the main context.
If the quoted content is not enough, use feishu_doc_read to read nearby context.
The quoted content is your primary anchor — insert/summarize/explain requests are about it.
Do not guess document content you haven't read.
Reply in the same language as the user's comment unless they request otherwise.
Use plain text only. Do not use Markdown, headings, bullet lists, tables, or code blocks.
Do not show your reasoning process. Do not start with "I will", "Let me", or "I'll first".
Output only the final user-facing reply.
If no reply is needed, output exactly NO_REPLY.
""".strip()


def build_local_comment_prompt(
    *,
    doc_title: str,
    doc_url: str,
    file_token: str,
    file_type: str,
    comment_id: str,
    quote_text: str,
    root_comment_text: str,
    target_reply_text: str,
    timeline: List[Tuple[str, str, bool]],  # [(user_id, text, is_self)]
    self_open_id: str,
    target_index: int = -1,
    referenced_docs: str = "",
) -> str:
    """Build the prompt for a local (quoted-text) comment."""
    selected = _select_local_timeline(timeline, target_index)

    lines = [
        f'The user added a reply in "{doc_title}".',
        f'Current user comment text: "{_truncate(target_reply_text)}"',
        f'Original comment text: "{_truncate(root_comment_text)}"',
        f'Quoted content: "{_truncate(quote_text, 500)}"',
        "This comment mentioned you (@mention is for routing, not task content).",
        f"Document link: {doc_url}",
        "Current commented document:",
        f"- file_type={file_type}",
        f"- file_token={file_token}",
        f"- comment_id={comment_id}",
        "",
        f"Current comment card timeline ({len(selected)}/{len(timeline)} entries):",
    ]

    for user_id, text, is_self in selected:
        marker = " <-- YOU" if is_self else ""
        lines.append(f"[{user_id}] {_truncate(text)}{marker}")

    if referenced_docs:
        lines.append(referenced_docs)

    lines.append("")
    lines.append(_COMMON_INSTRUCTIONS)
    return "\n".join(lines)


def build_whole_comment_prompt(
    *,
    doc_title: str,
    doc_url: str,
    file_token: str,
    file_type: str,
    comment_text: str,
    timeline: List[Tuple[str, str, bool]],  # [(user_id, text, is_self)]
    self_open_id: str,
    current_index: int = -1,
    nearest_self_index: int = -1,
    referenced_docs: str = "",
) -> str:
    """Build the prompt for a whole-document comment."""
    selected = _select_whole_timeline(timeline, current_index, nearest_self_index)

    lines = [
        f'The user added a comment in "{doc_title}".',
        f'Current user comment text: "{_truncate(comment_text)}"',
        "This is a whole-document comment.",
        "This comment mentioned you (@mention is for routing, not task content).",
        f"Document link: {doc_url}",
        "Current commented document:",
        f"- file_type={file_type}",
        f"- file_token={file_token}",
        "",
        f"Whole-document comment timeline ({len(selected)}/{len(timeline)} entries):",
    ]

    for user_id, text, is_self in selected:
        marker = " <-- YOU" if is_self else ""
        lines.append(f"[{user_id}] {_truncate(text)}{marker}")

    if referenced_docs:
        lines.append(referenced_docs)

    lines.append("")
    lines.append(_COMMON_INSTRUCTIONS)
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Agent execution
# ---------------------------------------------------------------------------


def _resolve_model_and_runtime() -> Tuple[str, dict]:
    """Resolve model and provider credentials, same as gateway message handling."""
    from gateway.run import _load_gateway_config, _resolve_gateway_model

    user_config = _load_gateway_config()
    model = _resolve_gateway_model(user_config)

    from gateway.run import _resolve_runtime_agent_kwargs
    runtime_kwargs = _resolve_runtime_agent_kwargs()

    # Fall back to provider's default model if none configured
    if not model and runtime_kwargs.get("provider"):
        try:
            from hermes_cli.models import get_default_model_for_provider
            model = get_default_model_for_provider(runtime_kwargs["provider"])
        except Exception:
            pass

    return model, runtime_kwargs


# ---------------------------------------------------------------------------
# Session cache for cross-card memory within the same document
# ---------------------------------------------------------------------------

import threading
import time as _time

_SESSION_MAX_MESSAGES = 50  # keep last N messages per document session
_SESSION_TTL_S = 3600       # expire sessions after 1 hour of inactivity

_session_cache_lock = threading.Lock()
_session_cache: Dict[str, Dict] = {}  # key -> {"messages": [...], "last_access": float}


def _session_key(file_type: str, file_token: str) -> str:
    return f"comment-doc:{file_type}:{file_token}"


def _load_session_history(key: str) -> List[Dict[str, Any]]:
    """Load conversation history for a document session."""
    with _session_cache_lock:
        entry = _session_cache.get(key)
        if entry is None:
            return []
        # Check TTL
        if _time.time() - entry["last_access"] > _SESSION_TTL_S:
            del _session_cache[key]
            logger.info("[Feishu-Comment] Session expired: %s", key)
            return []
        entry["last_access"] = _time.time()
        return list(entry["messages"])


def _save_session_history(key: str, messages: List[Dict[str, Any]]) -> None:
    """Save conversation history for a document session (keeps last N messages)."""
    # Only keep user/assistant messages (strip system messages and tool internals)
    cleaned = [
        m for m in messages
        if m.get("role") in ("user", "assistant") and m.get("content")
    ]
    # Keep last N
    if len(cleaned) > _SESSION_MAX_MESSAGES:
        cleaned = cleaned[-_SESSION_MAX_MESSAGES:]
    with _session_cache_lock:
        _session_cache[key] = {
            "messages": cleaned,
            "last_access": _time.time(),
        }
        logger.info("[Feishu-Comment] Session saved: %s (%d messages)", key, len(cleaned))


def _run_comment_agent(prompt: str, client: Any, session_key: str = "") -> str:
    """Create an AIAgent with feishu tools and run the prompt.

    If *session_key* is provided, loads/saves conversation history for
    cross-card memory within the same document.

    Returns the agent's final response text, or empty string on failure.
    """
    from run_agent import AIAgent

    logger.info("[Feishu-Comment] _run_comment_agent: injecting lark client into tool thread-locals")
    from tools.feishu_doc_tool import set_client as set_doc_client
    from tools.feishu_drive_tool import set_client as set_drive_client
    set_doc_client(client)
    set_drive_client(client)

    try:
        model, runtime_kwargs = _resolve_model_and_runtime()
        logger.info("[Feishu-Comment] _run_comment_agent: model=%s provider=%s base_url=%s",
                    model, runtime_kwargs.get("provider"), (runtime_kwargs.get("base_url") or "")[:50])

        # Load session history for cross-card memory
        history = _load_session_history(session_key) if session_key else []
        if history:
            logger.info("[Feishu-Comment] _run_comment_agent: loaded %d history messages from session %s",
                        len(history), session_key)

        agent = AIAgent(
            model=model,
            base_url=runtime_kwargs.get("base_url"),
            api_key=runtime_kwargs.get("api_key"),
            provider=runtime_kwargs.get("provider"),
            api_mode=runtime_kwargs.get("api_mode"),
            credential_pool=runtime_kwargs.get("credential_pool"),
            quiet_mode=True,
            skip_context_files=True,
            skip_memory=True,
            max_iterations=15,
            enabled_toolsets=["feishu_doc", "feishu_drive"],
        )
        logger.info("[Feishu-Comment] _run_comment_agent: calling run_conversation (prompt=%d chars, history=%d)",
                    len(prompt), len(history))
        result = agent.run_conversation(prompt, conversation_history=history or None)
        response = (result.get("final_response") or "").strip()
        api_calls = result.get("api_calls", 0)
        logger.info("[Feishu-Comment] _run_comment_agent: done api_calls=%d response_len=%d response=%s",
                    api_calls, len(response), response[:200])

        # Save updated history
        if session_key:
            new_messages = result.get("messages", [])
            if new_messages:
                _save_session_history(session_key, new_messages)

        return response
    except Exception as e:
        logger.exception("[Feishu-Comment] _run_comment_agent: agent failed: %s", e)
        return ""
    finally:
        set_doc_client(None)
        set_drive_client(None)


# ---------------------------------------------------------------------------
# Event handler entry point
# ---------------------------------------------------------------------------

_NO_REPLY_SENTINEL = "NO_REPLY"


_ALLOWED_NOTICE_TYPES = {"add_comment", "add_reply"}


async def handle_drive_comment_event(
    client: Any, data: Any, *, self_open_id: str = "",
) -> None:
    """Full orchestration for a drive comment event.

    1. Parse event + filter (self-reply, notice_type)
    2. Add OK reaction
    3. Fetch doc meta + comment details in parallel
    4. Branch on is_whole: build timeline
    5. Build prompt, run agent
    6. Deliver reply
    """
    logger.info("[Feishu-Comment] ========== handle_drive_comment_event START ==========")
    parsed = parse_drive_comment_event(data)
    if parsed is None:
        logger.warning("[Feishu-Comment] Dropping malformed drive comment event")
        return
    logger.info("[Feishu-Comment] [Step 0/5] Event parsed successfully")

    file_token = parsed["file_token"]
    file_type = parsed["file_type"]
    comment_id = parsed["comment_id"]
    reply_id = parsed["reply_id"]
    from_open_id = parsed["from_open_id"]
    to_open_id = parsed["to_open_id"]
    notice_type = parsed["notice_type"]

    # Filter: self-reply, receiver check, notice_type
    if from_open_id and self_open_id and from_open_id == self_open_id:
        logger.debug("[Feishu-Comment] Skipping self-authored event: from=%s", from_open_id)
        return
    if not to_open_id or (self_open_id and to_open_id != self_open_id):
        logger.debug("[Feishu-Comment] Skipping event not addressed to self: to=%s", to_open_id or "(empty)")
        return
    if notice_type and notice_type not in _ALLOWED_NOTICE_TYPES:
        logger.debug("[Feishu-Comment] Skipping notice_type=%s", notice_type)
        return
    if not file_token or not file_type or not comment_id:
        logger.warning("[Feishu-Comment] Missing required fields, skipping")
        return

    logger.info(
        "[Feishu-Comment] Event: notice=%s file=%s:%s comment=%s from=%s",
        notice_type, file_type, file_token, comment_id, from_open_id,
    )

    # Access control
    from gateway.platforms.feishu_comment_rules import load_config, resolve_rule, is_user_allowed, has_wiki_keys

    comments_cfg = load_config()
    rule = resolve_rule(comments_cfg, file_type, file_token)

    # If no exact match and config has wiki keys, try reverse-lookup
    if rule.match_source in ("wildcard", "top") and has_wiki_keys(comments_cfg):
        wiki_token = await _reverse_lookup_wiki_token(client, file_type, file_token)
        if wiki_token:
            rule = resolve_rule(comments_cfg, file_type, file_token, wiki_token=wiki_token)

    if not rule.enabled:
        logger.info("[Feishu-Comment] Comments disabled for %s:%s, skipping", file_type, file_token)
        return
    if not is_user_allowed(rule, from_open_id):
        logger.info("[Feishu-Comment] User %s denied (policy=%s, rule=%s)", from_open_id, rule.policy, rule.match_source)
        return

    logger.info("[Feishu-Comment] Access granted: user=%s policy=%s rule=%s", from_open_id, rule.policy, rule.match_source)
    if reply_id:
        asyncio.ensure_future(
            add_comment_reaction(
                client,
                file_token=file_token,
                file_type=file_type,
                reply_id=reply_id,
                reaction_type="OK",
            )
        )

    # Step 2: Parallel fetch -- doc meta + comment details
    logger.info("[Feishu-Comment] [Step 2/5] Parallel fetch: doc meta + comment batch_query")
    meta_task = asyncio.ensure_future(
        query_document_meta(client, file_token, file_type)
    )
    comment_task = asyncio.ensure_future(
        batch_query_comment(client, file_token, file_type, comment_id)
    )
    doc_meta, comment_detail = await asyncio.gather(meta_task, comment_task)

    doc_title = doc_meta.get("title", "Untitled")
    doc_url = doc_meta.get("url", "")
    is_whole = bool(comment_detail.get("is_whole"))

    logger.info(
        "[Feishu-Comment] Comment context: title=%s is_whole=%s",
        doc_title, is_whole,
    )

    # Step 3: Build timeline based on comment type
    logger.info("[Feishu-Comment] [Step 3/5] Building timeline (is_whole=%s)", is_whole)
    if is_whole:
        # Whole-document comment: fetch all whole comments as timeline
        logger.info("[Feishu-Comment] Fetching whole-document comments for timeline...")
        whole_comments = await list_whole_comments(client, file_token, file_type)

        timeline: List[Tuple[str, str, bool]] = []
        current_text = ""
        current_index = -1
        nearest_self_index = -1
        for wc in whole_comments:
            reply_list = wc.get("reply_list", {})
            if isinstance(reply_list, str):
                try:
                    reply_list = json.loads(reply_list)
                except (json.JSONDecodeError, TypeError):
                    reply_list = {}
            replies = reply_list.get("replies", [])
            for r in replies:
                uid = _get_reply_user_id(r)
                text = _extract_reply_text(r)
                is_self = (uid == self_open_id) if self_open_id else False
                idx = len(timeline)
                timeline.append((uid, text, is_self))
                if uid == from_open_id:
                    current_text = _extract_semantic_text(r, self_open_id)
                    current_index = idx
                if is_self:
                    nearest_self_index = idx

        if not current_text:
            for i, (uid, text, is_self) in reversed(list(enumerate(timeline))):
                if not is_self:
                    current_text = text
                    current_index = i
                    break

        logger.info("[Feishu-Comment] Whole timeline: %d entries, current_idx=%d, self_idx=%d, text=%s",
                    len(timeline), current_index, nearest_self_index,
                    current_text[:80] if current_text else "(empty)")

        # Extract and resolve document links from all replies
        all_raw_replies = []
        for wc in whole_comments:
            rl = wc.get("reply_list", {})
            if isinstance(rl, str):
                try:
                    rl = json.loads(rl)
                except (json.JSONDecodeError, TypeError):
                    rl = {}
            all_raw_replies.extend(rl.get("replies", []))
        doc_links = _extract_docs_links(all_raw_replies)
        if doc_links:
            doc_links = await _resolve_wiki_nodes(client, doc_links)
        ref_docs_text = _format_referenced_docs(doc_links, file_token)

        prompt = build_whole_comment_prompt(
            doc_title=doc_title,
            doc_url=doc_url,
            file_token=file_token,
            file_type=file_type,
            comment_text=current_text,
            timeline=timeline,
            self_open_id=self_open_id,
            current_index=current_index,
            nearest_self_index=nearest_self_index,
            referenced_docs=ref_docs_text,
        )

    else:
        # Local comment: fetch the comment thread replies
        logger.info("[Feishu-Comment] Fetching comment thread replies...")
        replies = await list_comment_replies(
            client, file_token, file_type, comment_id,
            expect_reply_id=reply_id,
        )

        quote_text = comment_detail.get("quote", "")

        timeline = []
        root_text = ""
        target_text = ""
        target_index = -1
        for i, r in enumerate(replies):
            uid = _get_reply_user_id(r)
            text = _extract_reply_text(r)
            is_self = (uid == self_open_id) if self_open_id else False
            timeline.append((uid, text, is_self))
            if i == 0:
                root_text = _extract_semantic_text(r, self_open_id)
            rid = r.get("reply_id", "")
            if rid and rid == reply_id:
                target_text = _extract_semantic_text(r, self_open_id)
                target_index = i

        if not target_text and timeline:
            for i, (uid, text, is_self) in reversed(list(enumerate(timeline))):
                if uid == from_open_id:
                    target_text = text
                    target_index = i
                    break

        logger.info("[Feishu-Comment] Local timeline: %d entries, target_idx=%d, quote=%s root=%s target=%s",
                    len(timeline), target_index,
                    quote_text[:60] if quote_text else "(empty)",
                    root_text[:60] if root_text else "(empty)",
                    target_text[:60] if target_text else "(empty)")

        # Extract and resolve document links from replies
        doc_links = _extract_docs_links(replies)
        if doc_links:
            doc_links = await _resolve_wiki_nodes(client, doc_links)
        ref_docs_text = _format_referenced_docs(doc_links, file_token)

        prompt = build_local_comment_prompt(
            doc_title=doc_title,
            doc_url=doc_url,
            file_token=file_token,
            file_type=file_type,
            comment_id=comment_id,
            quote_text=quote_text,
            root_comment_text=root_text,
            target_reply_text=target_text,
            timeline=timeline,
            self_open_id=self_open_id,
            target_index=target_index,
            referenced_docs=ref_docs_text,
        )

    logger.info("[Feishu-Comment] [Step 4/5] Prompt built (%d chars), running agent...", len(prompt))
    logger.debug("[Feishu-Comment] Full prompt:\n%s", prompt)

    # Step 4: Run agent in a thread (run_conversation is synchronous)
    # Session key groups all comment cards on the same document
    sess_key = _session_key(file_type, file_token)
    loop = asyncio.get_running_loop()
    response = await loop.run_in_executor(
        None, _run_comment_agent, prompt, client, sess_key,
    )

    if not response or _NO_REPLY_SENTINEL in response:
        logger.info("[Feishu-Comment] Agent returned NO_REPLY, skipping delivery")
    else:
        logger.info("[Feishu-Comment] Agent response (%d chars): %s", len(response), response[:200])

        # Step 5: Deliver reply
        logger.info("[Feishu-Comment] [Step 5/5] Delivering reply (is_whole=%s, comment_id=%s)", is_whole, comment_id)
        success = await deliver_comment_reply(
            client, file_token, file_type, comment_id, response, is_whole,
        )
        if success:
            logger.info("[Feishu-Comment] Reply delivered successfully")
        else:
            logger.error("[Feishu-Comment] Failed to deliver reply")

    # Cleanup: remove OK reaction (best-effort, non-blocking)
    if reply_id:
        await delete_comment_reaction(
            client,
            file_token=file_token,
            file_type=file_type,
            reply_id=reply_id,
            reaction_type="OK",
        )

    logger.info("[Feishu-Comment] ========== handle_drive_comment_event END ==========")
