codex-app-server/cloud/chv/presentation.py

"""P8 presentation：后台任务完成后“是否值得呈现”的评估，与
通知去重节流账本。

对齐 Muse B2（官方设计文）：完成后台工作后评估是否值得呈现，
只在真正有新内容或需要输入时通知用户。

判定是确定性规则（不是模型判断）：
- needs_input：需要用户输入 -> 通知。
- failed/interrupted：失败、需要决策 -> 通知。
- completed 且有实质新内容（新产物、改动文件、或显式 notify
  标志）-> 通知；否则常规完成只记日志。
- cancelled / 未知终态 -> 只记日志（未知终态 fail-closed，
  不通知）。

账本：宿主级 AppStateStore（round-12 已迁移，见
docs/chv-muse-p8-gap.md §6）：state_dir/app-state.sqlite 的
``p8-ledger`` 命名空间，一行存整份账本；旧
notification-ledger.json 首次加载时自动导入并改名
``.migrated``；行损坏/库打不开时回空账本（去重信息丢了只会
导致一次重复通知，不影响任务本身），下次成功保存即覆盖自愈。
同一任务同一原因在节流窗口（3600 秒，本项目自定）内只通知一次。
"""

from __future__ import annotations

import json
import logging
import os
import time

from cloud.chv.app_state import AppStateStore, host_state_db_path

_LOGGER = logging.getLogger("cloud.cloud_hypervisor")

# 同一任务同一原因的通知节流窗口（秒，本项目自定）。
NOTIFY_THROTTLE_SECONDS = 3600
_LEDGER_FILENAME = "notification-ledger.json"
_KV_NAMESPACE = "p8-ledger"
_KV_KEY = "registry"
_MAX_LEDGER_ENTRIES = 500


def evaluate_presentation(result: dict) -> dict:
    """评估一次后台任务终态是否值得呈现。

    result 键：status（completed/failed/interrupted/cancelled/
    needs_input）、new_artifacts（list）、changed_files（list）、
    notify（bool，任务显式要求通知）。返回 {"present", "reason"}；
    present 为 False 时调用方只记日志、不通知。"""
    if not isinstance(result, dict):
        return {"present": False, "reason": "unknown_status"}
    status = result.get("status")
    if status == "needs_input":
        return {"present": True, "reason": "needs_input"}
    if status in ("failed", "interrupted"):
        return {"present": True, "reason": "failed_needs_decision"}
    if status == "completed":
        return _evaluate_completed(result)
    if status == "cancelled":
        return {"present": False, "reason": "cancelled"}
    return {"present": False, "reason": "unknown_status"}


def _evaluate_completed(result: dict) -> dict:
    """完成态分支：有实质新内容才通知。"""
    artifacts = result.get("new_artifacts")
    changed = result.get("changed_files")
    has_new = bool(result.get("notify"))
    if isinstance(artifacts, list) and artifacts:
        has_new = True
    if isinstance(changed, list) and changed:
        has_new = True
    if has_new:
        return {"present": True, "reason": "substantive_new_content"}
    return {"present": False, "reason": "routine_completed"}


def _open_store(state_dir: str) -> AppStateStore:
    """打开宿主级状态库（每次调用新建连接，用完即关）。"""
    store = AppStateStore(host_state_db_path(state_dir))
    store.open()
    return store


def _ledger_path(state_dir: str) -> str:
    """旧版通知账本文件路径（只用于一次性迁移导入）。"""
    return os.path.join(state_dir, _LEDGER_FILENAME)


def _quarantine(path: str) -> None:
    """把损坏的账本挪到 <path>.corrupt 旁（尽力而为）。"""
    try:
        os.replace(path, path + ".corrupt")
    except OSError:
        _LOGGER.warning("chv_ledger_quarantine_failed path=%s", path)


def _load_ledger(state_dir: str) -> dict:
    """读账本：KV 行缺失时走一次性旧文件导入；行损坏/库打不
    开时回空结构（去重信息丢了只会导致一次重复通知，不影响
    任务本身；下次成功保存即覆盖自愈）。"""
    try:
        with _open_store(state_dir) as store:
            raw = store.kv_get(_KV_NAMESPACE, _KV_KEY)
    except Exception:
        _LOGGER.warning("chv_ledger_store_unreadable state_dir=%s",
                        state_dir)
        return {"notified": {}}
    if raw is None:
        return _import_legacy(state_dir)
    try:
        data = json.loads(raw)
    except ValueError:
        _LOGGER.warning("chv_ledger_corrupt state_dir=%s", state_dir)
        return {"notified": {}}
    if not isinstance(data, dict) \
            or not isinstance(data.get("notified"), dict):
        return {"notified": {}}
    return data


def _import_legacy(state_dir: str) -> dict:
    """一次性导入旧 notification-ledger.json：合法即进 KV 并
    把文件改名 ``.migrated``；无文件回空；损坏则 quarantine
    后回空（旧口径）。导入失败时返回读到的数据、文件保留，
    下次加载重试。"""
    path = _ledger_path(state_dir)
    try:
        with open(path, "r") as fh:
            data = json.load(fh)
    except FileNotFoundError:
        return {"notified": {}}
    except (OSError, ValueError):
        _quarantine(path)
        return {"notified": {}}
    if not isinstance(data, dict) \
            or not isinstance(data.get("notified"), dict):
        _quarantine(path)
        return {"notified": {}}
    try:
        with _open_store(state_dir) as store:
            store.kv_put(_KV_NAMESPACE, _KV_KEY, json.dumps(data))
    except Exception:
        _LOGGER.warning("chv_ledger_import_failed state_dir=%s",
                        state_dir)
        return data
    try:
        os.replace(path, path + ".migrated")
    except OSError:
        pass
    return data


def _save_ledger(state_dir: str, data: dict) -> None:
    """落盘账本到 KV 行（截断到上限）；写失败只记日志。"""
    notified = data.get("notified", {})
    if len(notified) > _MAX_LEDGER_ENTRIES:
        items = sorted(notified.items(), key=lambda kv: kv[1])
        data["notified"] = dict(items[-_MAX_LEDGER_ENTRIES:])
    try:
        with _open_store(state_dir) as store:
            store.kv_put(_KV_NAMESPACE, _KV_KEY, json.dumps(data))
    except Exception:
        _LOGGER.warning("chv_ledger_save_failed state_dir=%s", state_dir)


class NotificationLedger:
    """通知去重节流账本（每任务每原因节流）。

    should_notify(task_id, reason) 在窗口内未通知过时回 True
    并记下这次通知；窗口内已通知过回 False。账本落在宿主级
    AppStateStore（round-12 已迁移，见模块 docstring）。
    """

    def __init__(self, state_dir: str) -> None:
        """建账本：state_dir 为空即 ValueError。"""
        if not state_dir or not isinstance(state_dir, str):
            raise ValueError("state_dir required")
        self.state_dir = state_dir

    def should_notify(self, task_id: str, reason: str,
                      now: float | None = None) -> bool:
        """该任务该原因现在能不能通知：窗口内没通知过就记下
        并回 True，否则回 False。task_id/reason 为空即
        ValueError。"""
        if now is None:
            now = time.time()
        if not task_id or not isinstance(task_id, str):
            raise ValueError("task_id required")
        if not reason or not isinstance(reason, str):
            raise ValueError("reason required")
        key = "%s:%s" % (task_id, reason)
        data = _load_ledger(self.state_dir)
        notified = data.get("notified", {})
        last = notified.get(key)
        if isinstance(last, (int, float)) \
                and now - last < NOTIFY_THROTTLE_SECONDS:
            return False
        notified[key] = now
        _save_ledger(self.state_dir, data)
        return True


def present_or_log(result: dict, ledger: NotificationLedger,
                   task_id: str,
                   now: float | None = None) -> dict:
    """评估 + 去重的一站式入口（worker/push 终态派发处调它）。

    返回 {"present", "reason", "notified"}：present 是评估结论，
    notified 是本次是否真的发出通知（评估通过但窗口内已通知
    过时 notified 为 False、只记日志）。"""
    if now is None:
        now = time.time()
    decision = evaluate_presentation(result)
    if not decision["present"]:
        return {"present": False, "reason": decision["reason"],
                "notified": False}
    notified = ledger.should_notify(task_id, decision["reason"], now)
    return {"present": True, "reason": decision["reason"],
            "notified": notified}