wechatbridge-cli 1.3.0__py3-none-any.whl

wechatbridge/runner_common.py

@@ -0,0 +1,1003 @@
+"""Shared logic for agy and grok CLI backends.
+
+Contains session isolation, preference persistence, output cleanup,
+dangerous prompt detection, and process management helpers used by
+both agy.py and grok.py.
+"""
+
+import asyncio
+import hashlib
+import json
+import logging
+import os
+import re
+import shutil
+import signal
+import sys
+import time
+
+from .config import config
+
+logger = logging.getLogger("wechatbridge.runner")
+
+# ANSI escape code pattern
+ANSI_RE = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+# HTML tag pattern
+HTML_TAG_RE = re.compile(r"<[^>]+>")
+
+# Sensitive env var prefixes to strip from child process environments
+_SENSITIVE_PREFIXES = (
+    "TOKEN", "KEY", "SECRET", "PASSWORD",
+    "AWS", "GITHUB", "GITLAB", "CREDENTIAL",
+)
+# Segment names that mark a var as secret when they appear as a path part
+_SENSITIVE_SEGMENTS = frozenset({
+    "TOKEN", "KEY", "SECRET", "PASSWORD", "PASSWD",
+    "CREDENTIAL", "CREDENTIALS", "APIKEY", "API_KEY",
+})
+_SENSITIVE_SUFFIXES = (
+    "_TOKEN", "_KEY", "_SECRET", "_PASSWORD", "_PASSWD",
+    "_CREDENTIAL", "_CREDENTIALS", "_APIKEY",
+)
+
+
+def sanitize_user_id(user_id: str) -> str:
+    """Convert a WeChat user ID to a filesystem-safe directory name.
+
+    Uses a short hash suffix for uniqueness while keeping a readable prefix.
+    """
+    h = hashlib.sha256(user_id.encode()).hexdigest()[:12]
+    safe = re.sub(r"[^a-zA-Z0-9_]", "_", user_id)[:48]
+    return f"{safe}_{h}"
+
+
+def get_session_dir(user_id: str) -> str:
+    """Get the per-user session directory path."""
+    return os.path.join(config.session_base_dir, sanitize_user_id(user_id))
+
+
+def ensure_session_dir(user_id: str) -> str:
+    """Create per-user session dir with mode 0700 and return its path."""
+    path = get_session_dir(user_id)
+    try:
+        os.makedirs(path, exist_ok=True)
+        os.chmod(path, 0o700)
+    except OSError as e:
+        logger.warning("Failed to ensure session dir %s: %s", path, e)
+    return path
+
+
+def path_is_under(path: str, root: str) -> bool:
+    """True if path is the same as root or a realpath child of root."""
+    try:
+        real = os.path.realpath(path)
+        root_real = os.path.realpath(root)
+    except OSError:
+        return False
+    if real == root_real:
+        return True
+    prefix = root_real if root_real.endswith(os.sep) else root_real + os.sep
+    return real.startswith(prefix)
+
+
+def validate_add_dir(path: str, user_id: str) -> tuple[bool, str]:
+    """Validate /add-dir path: must exist as dir and sit under allowed roots.
+
+    Session dir is always allowed; extra roots from config.add_dir_roots.
+    Returns (ok, message_or_resolved_path).
+    """
+    raw = (path or "").strip()
+    if not raw:
+        return False, "路径为空"
+    expanded = os.path.expanduser(raw)
+    if not os.path.isabs(expanded):
+        # Relative paths resolve against session dir
+        expanded = os.path.join(get_session_dir(user_id), expanded)
+    try:
+        resolved = os.path.realpath(expanded)
+    except OSError as e:
+        return False, f"无法解析路径: {e}"
+    if not os.path.isdir(resolved):
+        return False, "路径不存在或不是目录"
+
+    allowed_roots = [get_session_dir(user_id)]
+    for r in getattr(config, "add_dir_roots", []) or []:
+        if r:
+            allowed_roots.append(os.path.expanduser(r))
+
+    if not any(path_is_under(resolved, root) for root in allowed_roots):
+        return False, (
+            "路径不在允许范围内。"
+            "仅允许会话目录"
+            + (" 或 WECHATBRIDGE_ADD_DIR_ROOTS 内路径" if config.add_dir_roots else "")
+            + "。"
+        )
+    return True, resolved
+
+
+def is_first_message(session_dir: str) -> bool:
+    """Check if this user has no existing conversation."""
+    return not os.path.exists(os.path.join(session_dir, ".initialized"))
+
+
+def mark_initialized(session_dir: str) -> None:
+    """Create .initialized flag file after first message."""
+    try:
+        os.makedirs(session_dir, exist_ok=True)
+        try:
+            os.chmod(session_dir, 0o700)
+        except OSError:
+            pass
+        with open(os.path.join(session_dir, ".initialized"), "w") as f:
+            f.write("1")
+    except OSError as e:
+        logger.error("Failed to mark session initialized: %s", e)
+
+
+def clean_output(text: str) -> str:
+    """Remove ANSI escape codes and HTML tags from CLI output."""
+    text = ANSI_RE.sub("", text)
+    text = HTML_TAG_RE.sub("", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()
+
+
+# ---------------------------------------------------------------------------
+# WeChat error reply format (fixed header + body)
+# ---------------------------------------------------------------------------
+
+# Shown when CLI returns successfully but with no display text
+EMPTY_REPLY = "（无回复内容）"
+
+
+def format_error(title: str, detail: str = "") -> str:
+    """Standard error bubble: header line only, body below.
+
+    Example:
+        ❌ **未登录** ❌
+
+        Grok 凭证不可用。
+    """
+    title = (title or "错误").strip().replace("\n", " ")
+    detail = (detail or "").strip()
+    if detail:
+        return f"❌ **{title}** ❌\n\n{detail}"
+    return f"❌ **{title}** ❌"
+
+
+def format_cli_error(raw_message: str, *, backend: str = "") -> str:
+    """Map CLI stderr/JSON error text into Chinese title + fixed header.
+
+    Never put the whole raw English blob into the ❌ **...** ❌ title line.
+    Known cases get a Chinese title + short Chinese explanation; raw text
+    is kept under「原始信息」only when it is not already Chinese-heavy.
+    """
+    raw = clean_output(raw_message or "") or "未知错误"
+    lower = raw.lower()
+    backend = (backend or "").strip().lower()
+    name = "Grok" if backend == "grok" else ("agy" if backend == "agy" else "CLI")
+
+    def _with_raw(title: str, zh: str) -> str:
+        # Avoid duplicating if raw is already the zh line
+        if raw.strip() == zh.strip():
+            return format_error(title, zh)
+        return format_error(title, f"{zh}\n\n原始信息：\n{raw}")
+
+    # Auth / login
+    if (
+        "not signed in" in lower
+        or "authenticate" in lower
+        or "login --device" in lower
+        or "grok login" in lower
+        or "please log in" in lower
+        or "please login" in lower
+        or "not authenticated" in lower
+        or "unauthorized" in lower
+        or "401" in lower and ("auth" in lower or "token" in lower or "login" in lower)
+        or ("xai_api_key" in lower and ("sign" in lower or "login" in lower or "auth" in lower))
+    ):
+        return _with_raw(
+            "未登录",
+            f"{name} 未登录，或读不到有效凭证。"
+            + (" 请在本机执行 `grok login --device-code`，或设置 `XAI_API_KEY`。" if backend == "grok" else " 请检查本机登录/凭证是否有效。"),
+        )
+
+    # Rate limit / quota
+    if (
+        "rate limit" in lower
+        or "rate_limit" in lower
+        or "too many requests" in lower
+        or "quota" in lower
+        or "resource exhausted" in lower
+        or "429" in lower
+    ):
+        return _with_raw("请求过于频繁", "触发限流或额度不足，请稍后再试。")
+
+    # Network
+    if (
+        "connection refused" in lower
+        or "connection reset" in lower
+        or "network is unreachable" in lower
+        or "name or service not known" in lower
+        or "temporary failure in name resolution" in lower
+        or "ssl" in lower and ("error" in lower or "certificate" in lower)
+        or "econnreset" in lower
+        or "econnrefused" in lower
+        or "fetch failed" in lower
+        or "socket hang up" in lower
+    ):
+        return _with_raw("网络错误", "连不上服务，请检查网络后重试。")
+
+    # Cascade / API hang (agy)
+    if "timeout waiting for cascade" in lower or "timeout waiting for response" in lower:
+        return _with_raw("级联超时", "模型 API 级联推理超时，请稍后重试或简化指令。")
+
+    if "permission" in lower and ("denied" in lower or "refuse" in lower or "rejected" in lower):
+        return _with_raw("权限不足", "没有执行该操作的权限。")
+
+    if "timeout" in lower or "timed out" in lower or "deadline exceeded" in lower:
+        return _with_raw("超时", "等待响应超时，请稍后重试。")
+
+    if "model" in lower and (
+        "not found" in lower
+        or "unknown" in lower
+        or "invalid" in lower
+        or "does not exist" in lower
+        or "unsupported" in lower
+        or "not supported" in lower
+        or "no such" in lower
+    ):
+        return _with_raw("模型无效", "指定的模型不可用，请用 `/models` 查看后重选。")
+
+    if "command not found" in lower or "not a command" in lower:
+        return _with_raw("命令不可用", f"{name} 可执行文件可能未安装或不在 PATH 中。")
+
+    if "not found" in lower or "no such file" in lower or "enoent" in lower:
+        return _with_raw("未找到", "请求的资源或文件不存在。")
+
+    # Generic CLI failure — short Chinese title, body is raw (may still be English)
+    title = "执行失败"
+    if backend == "grok":
+        title = "Grok 执行失败"
+    elif backend == "agy":
+        title = "agy 执行失败"
+    return format_error(title, raw)
+
+
+# ---------------------------------------------------------------------------
+# Per-user preference persistence (per-backend model/effort/mode memory)
+# ---------------------------------------------------------------------------
+
+KNOWN_BACKENDS = ("agy", "grok")
+BACKEND_SCOPED_KEYS = ("model", "effort", "mode")
+
+
+def _default_backend() -> str:
+    b = getattr(config, "backend", "agy") or "agy"
+    return b if b in KNOWN_BACKENDS else "agy"
+
+
+def _empty_backend_slot() -> dict:
+    return {"model": "", "effort": "", "mode": ""}
+
+
+def _slot_from(data) -> dict:
+    """Normalize a by_backend slot to model/effort/mode strings."""
+    if not isinstance(data, dict):
+        return _empty_backend_slot()
+    return {
+        "model": data.get("model") or "",
+        "effort": data.get("effort") or "",
+        "mode": data.get("mode") or "",
+    }
+
+
+def default_prefs() -> dict:
+    """Fresh prefs: empty model/effort/mode means CLI built-in default."""
+    backend = _default_backend()
+    return {
+        "model": "",
+        "effort": "",
+        "mode": "",
+        "add_dirs": [],
+        "backend": backend,
+        "by_backend": {b: _empty_backend_slot() for b in KNOWN_BACKENDS},
+    }
+
+
+def normalize_prefs(data: dict | None) -> dict:
+    """Fill defaults, migrate flat prefs → by_backend, ensure structure.
+
+    Migration (no by_backend yet): copy top-level model/effort/mode into the
+    *current* backend slot only; other backends stay empty (project default).
+    """
+    base = default_prefs()
+    if not isinstance(data, dict):
+        return base
+
+    backend = data.get("backend") or base["backend"]
+    if backend not in KNOWN_BACKENDS:
+        backend = base["backend"]
+
+    model = data.get("model") if data.get("model") is not None else ""
+    effort = data.get("effort") if data.get("effort") is not None else ""
+    mode = data.get("mode") if data.get("mode") is not None else ""
+    if not isinstance(model, str):
+        model = str(model) if model else ""
+    if not isinstance(effort, str):
+        effort = str(effort) if effort else ""
+    if not isinstance(mode, str):
+        mode = str(mode) if mode else ""
+
+    add_dirs = data.get("add_dirs", [])
+    if not isinstance(add_dirs, list):
+        add_dirs = []
+
+    raw_by = data.get("by_backend")
+    if isinstance(raw_by, dict):
+        by_backend = {b: _slot_from(raw_by.get(b)) for b in KNOWN_BACKENDS}
+        # Keep any extra backend keys only if well-formed (forward-compatible)
+        for k, v in raw_by.items():
+            if k not in by_backend and isinstance(v, dict):
+                by_backend[k] = _slot_from(v)
+    else:
+        # Legacy flat file: attribute current active fields to current backend only
+        by_backend = {b: _empty_backend_slot() for b in KNOWN_BACKENDS}
+        by_backend[backend] = {
+            "model": model or "",
+            "effort": effort or "",
+            "mode": mode or "",
+        }
+
+    return {
+        "model": model or "",
+        "effort": effort or "",
+        "mode": mode or "",
+        "add_dirs": add_dirs,
+        "backend": backend,
+        "by_backend": by_backend,
+    }
+
+
+def sync_active_to_memory(prefs: dict) -> None:
+    """Write top-level model/effort/mode into by_backend[current backend]."""
+    backend = prefs.get("backend") or _default_backend()
+    if backend not in KNOWN_BACKENDS:
+        backend = _default_backend()
+        prefs["backend"] = backend
+    by = prefs.setdefault("by_backend", {})
+    if not isinstance(by, dict):
+        by = {}
+        prefs["by_backend"] = by
+    slot = _empty_backend_slot()
+    for k in BACKEND_SCOPED_KEYS:
+        slot[k] = prefs.get(k) or ""
+    by[backend] = slot
+    # Ensure sibling backends exist
+    for b in KNOWN_BACKENDS:
+        if b not in by or not isinstance(by.get(b), dict):
+            by[b] = _empty_backend_slot()
+
+
+def apply_memory_to_active(prefs: dict, backend: str) -> None:
+    """Load by_backend[backend] into top-level model/effort/mode.
+
+    Empty slot → empty active fields (CLI default / project default).
+    """
+    if backend not in KNOWN_BACKENDS:
+        backend = _default_backend()
+    by = prefs.get("by_backend") if isinstance(prefs.get("by_backend"), dict) else {}
+    slot = _slot_from(by.get(backend))
+    for k in BACKEND_SCOPED_KEYS:
+        prefs[k] = slot.get(k) or ""
+
+
+def switch_backend_prefs(prefs: dict, new_backend: str) -> tuple[str, str]:
+    """Snapshot current backend memory, switch, restore target memory.
+
+    Returns (old_backend, new_backend). Mutates prefs in place.
+    First visit to a backend leaves model/effort/mode empty (CLI default).
+    """
+    if new_backend not in KNOWN_BACKENDS:
+        raise ValueError(f"unknown backend: {new_backend}")
+    old = prefs.get("backend") or _default_backend()
+    if old not in KNOWN_BACKENDS:
+        old = _default_backend()
+    # Persist whatever is active under the backend we are leaving
+    prefs["backend"] = old
+    sync_active_to_memory(prefs)
+    prefs["backend"] = new_backend
+    apply_memory_to_active(prefs, new_backend)
+    # Keep target slot materialised even if empty
+    sync_active_to_memory(prefs)
+    return old, new_backend
+
+
+def update_active_prefs(user_id: str, **fields) -> dict:
+    """Load prefs, update top-level fields, mirror into current backend memory, save.
+
+    Use for /model, /fast, /planning and any backend-scoped preference change.
+    Unknown keys are still written to the top level (e.g. add_dirs) but only
+    model/effort/mode are mirrored into by_backend.
+    """
+    prefs = load_prefs(user_id)
+    for k, v in fields.items():
+        if v is None:
+            prefs[k] = "" if k in BACKEND_SCOPED_KEYS else v
+        else:
+            prefs[k] = v
+    if any(k in BACKEND_SCOPED_KEYS for k in fields):
+        sync_active_to_memory(prefs)
+    save_prefs(user_id, prefs)
+    return prefs
+
+
+def format_model_label(model: str) -> str:
+    """Human-readable model for switch replies."""
+    model = (model or "").strip()
+    if not model:
+        return "后端默认（未指定）"
+    return model
+
+
+def load_prefs(user_id: str) -> dict:
+    """Load per-user preferences from prefs.json (normalized + migrated).
+
+    After normalize, active model/effort/mode are re-aligned from
+    by_backend[current] so a stale top-level field cannot outlive memory.
+    """
+    session_dir = get_session_dir(user_id)
+    prefs_path = os.path.join(session_dir, "prefs.json")
+    try:
+        if os.path.exists(prefs_path):
+            with open(prefs_path, "r") as f:
+                data = json.load(f)
+            prefs = normalize_prefs(data)
+            apply_memory_to_active(prefs, prefs.get("backend") or _default_backend())
+            return prefs
+    except (OSError, json.JSONDecodeError) as e:
+        logger.warning("Failed to load prefs for %s: %s", user_id, e)
+    return default_prefs()
+
+
+def save_prefs(user_id: str, prefs: dict) -> None:
+    """Save per-user preferences to prefs.json (normalized structure)."""
+    session_dir = get_session_dir(user_id)
+    os.makedirs(session_dir, exist_ok=True)
+    prefs_path = os.path.join(session_dir, "prefs.json")
+    try:
+        payload = normalize_prefs(prefs)
+        # Prefer caller's active fields / backend / add_dirs / by_backend
+        for k in BACKEND_SCOPED_KEYS:
+            if k in prefs:
+                payload[k] = prefs.get(k) or ""
+        if prefs.get("backend") in KNOWN_BACKENDS:
+            payload["backend"] = prefs["backend"]
+        if isinstance(prefs.get("add_dirs"), list):
+            payload["add_dirs"] = prefs["add_dirs"]
+        if isinstance(prefs.get("by_backend"), dict):
+            for b, slot in prefs["by_backend"].items():
+                payload["by_backend"][b] = _slot_from(slot)
+            for b in KNOWN_BACKENDS:
+                payload["by_backend"].setdefault(b, _empty_backend_slot())
+        # Current backend slot always mirrors active model/effort/mode
+        sync_active_to_memory(payload)
+        with open(prefs_path, "w") as f:
+            json.dump(payload, f, ensure_ascii=False, indent=2)
+        # Keep caller's dict in sync with what was written
+        prefs.update(payload)
+    except OSError as e:
+        logger.error("Failed to save prefs for %s: %s", user_id, e)
+
+
+# ---------------------------------------------------------------------------
+# Dangerous prompt detection
+# ---------------------------------------------------------------------------
+
+# Confirm gate: hardcoded dangerous keyword fallbacks (used when config.confirm_keywords is empty)
+# Prefer concrete shell/destructive patterns; avoid bare Chinese words like「删除」that false-positive daily chat.
+_DANGEROUS_KEYWORDS = [
+    "rm -rf /", "rm -rf/*", "rm -rf ~", "rm -rf~",
+    "curl |sh", "curl|sh", "curl | bash", "curl|bash",
+    "wget -o- | sh", "wget|sh", "wget|bash",
+    "mkfs.", "mkfs ", "dd if=", ":(){", "fork bomb",
+    "chmod -r 777 /", "chmod -r 777/",
+    "drop table", "drop database",
+    "format c:", "del /f /s",
+    "格式化磁盘", "格式化硬盘", "清空系统", "删掉所有", "删除全部",
+    "卸载系统",
+]
+
+
+def is_dangerous(prompt: str) -> bool:
+    """Check if a prompt contains dangerous keywords.
+
+    Uses config.confirm_keywords if non-empty, otherwise falls back to
+    the hardcoded _DANGEROUS_KEYWORDS list.
+    """
+    keywords = config.confirm_keywords if config.confirm_keywords else _DANGEROUS_KEYWORDS
+    lower = prompt.lower()
+    for kw in keywords:
+        if kw.lower() in lower:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Model/effort parsing
+# ---------------------------------------------------------------------------
+
+def parse_model_effort(model: str) -> tuple[str, str | None]:
+    """Split 'gemini-3.6-flash-high' -> ('gemini-3.6-flash', 'high').
+
+    Returns (base_model, embedded_effort) where embedded_effort is None if
+    the model name does not end with -high, -medium, or -low.
+    """
+    for suffix in ("-high", "-medium", "-low"):
+        if model.endswith(suffix):
+            base = model[: -len(suffix)]
+            effort = suffix[1:]  # strip leading dash
+            return base, effort
+    return model, None
+
+
+# ---------------------------------------------------------------------------
+# Subprocess environment and process management
+# ---------------------------------------------------------------------------
+
+def _is_sensitive_env_name(name: str) -> bool:
+    """True if env var name looks like a secret (prefix, segment, or suffix)."""
+    u = (name or "").upper()
+    if not u:
+        return False
+    if u.startswith(_SENSITIVE_PREFIXES):
+        return True
+    if u.endswith(_SENSITIVE_SUFFIXES):
+        return True
+    if "API_KEY" in u or "ACCESS_KEY" in u or "SECRET_KEY" in u or "AUTH_TOKEN" in u:
+        return True
+    for part in re.split(r"[._-]+", u):
+        if part in _SENSITIVE_SEGMENTS:
+            return True
+    return False
+
+
+def sanitize_env(session_dir: str) -> dict:
+    """Build a clean environment dict for CLI subprocesses.
+
+    Strips sensitive vars (including XAI_API_KEY / OPENAI_API_KEY style names),
+    sets HOME (and USERPROFILE on Windows) to session_dir for per-user isolation.
+    """
+    env = {
+        k: v for k, v in os.environ.items()
+        if not _is_sensitive_env_name(k)
+    }
+    env["HOME"] = session_dir
+    if sys.platform == "win32":
+        env["USERPROFILE"] = session_dir
+    return env
+
+
+# Temporary / cache roots under each user session (safe to expire file-by-file).
+_SESSION_TEMP_REL_DIRS = (
+    "images",
+    "files",
+    ".cache",
+    os.path.join(".gemini", "antigravity-cli", "scratch"),
+    os.path.join(".gemini", "antigravity-cli", "crashes"),
+    os.path.join(".gemini", "antigravity-cli", "log"),
+    os.path.join(".gemini", "antigravity-cli", "cache"),
+    os.path.join(".grok", "logs"),
+)
+
+# Dialogue history — cleaned as *units* (never split SQLite sidecars / session trees).
+_HISTORY_CONVERSATIONS_REL = os.path.join(
+    ".gemini", "antigravity-cli", "conversations"
+)
+_HISTORY_BRAIN_REL = os.path.join(".gemini", "antigravity-cli", "brain")
+_HISTORY_KNOWLEDGE_REL = os.path.join(".gemini", "antigravity-cli", "knowledge")
+_HISTORY_GROK_SESSIONS_REL = os.path.join(".grok", "sessions")
+
+_SESSION_HISTORY_REL_DIRS = (
+    _HISTORY_CONVERSATIONS_REL,
+    _HISTORY_BRAIN_REL,
+    _HISTORY_KNOWLEDGE_REL,
+    _HISTORY_GROK_SESSIONS_REL,
+)
+
+# SQLite sidecar suffixes that must share fate with the main ``*.db`` file.
+_SQLITE_SIDECAR_TAILS = ("-wal", "-shm", "-journal")
+
+
+def _remove_old_files_under(root: str, cutoff: float) -> int:
+    """Delete files under root older than cutoff; prune empty subdirs.
+
+    For independent temp files only (images/cache/scratch). Does not remove
+    ``root`` itself. Returns number of files removed.
+    """
+    if not os.path.isdir(root):
+        return 0
+    removed = 0
+    try:
+        for dirpath, dirnames, filenames in os.walk(root, topdown=False):
+            for fn in filenames:
+                path = os.path.join(dirpath, fn)
+                try:
+                    if not os.path.isfile(path) and not os.path.islink(path):
+                        continue
+                    if os.path.getmtime(path) < cutoff:
+                        os.remove(path)
+                        removed += 1
+                        logger.info("Session cleanup: removed %s", path)
+                except OSError as e:
+                    logger.warning("Session cleanup failed %s: %s", path, e)
+            if dirpath == root:
+                continue
+            try:
+                if not os.listdir(dirpath):
+                    os.rmdir(dirpath)
+            except OSError:
+                pass
+    except OSError as e:
+        logger.warning("Session cleanup walk failed %s: %s", root, e)
+    return removed
+
+
+def _file_mtime(path: str) -> float | None:
+    try:
+        return os.path.getmtime(path)
+    except OSError:
+        return None
+
+
+def _tree_newest_mtime(root: str) -> float | None:
+    """Newest *file* mtime under root (directory mtimes are ignored).
+
+    Parent dirs get a fresh mtime on mkdir/unlink of children; using them would
+    keep idle trees forever or falsely mark them active. Empty trees fall back
+    to the directory mtime so empty shells can still be pruned.
+    """
+    if os.path.isfile(root) or os.path.islink(root):
+        return _file_mtime(root)
+    if not os.path.isdir(root):
+        return _file_mtime(root)
+    newest: float | None = None
+    try:
+        for dirpath, _, filenames in os.walk(root):
+            for fn in filenames:
+                m = _file_mtime(os.path.join(dirpath, fn))
+                if m is not None and (newest is None or m > newest):
+                    newest = m
+    except OSError as e:
+        logger.warning("Session cleanup mtime walk failed %s: %s", root, e)
+    if newest is None:
+        return _file_mtime(root)
+    return newest
+
+
+def _paths_newest_mtime(paths: list[str]) -> float | None:
+    newest: float | None = None
+    for path in paths:
+        if os.path.isdir(path) and not os.path.islink(path):
+            m = _tree_newest_mtime(path)
+        else:
+            m = _file_mtime(path)
+        if m is not None and (newest is None or m > newest):
+            newest = m
+    return newest
+
+
+def _delete_path_unit(path: str) -> int:
+    """Remove a file or directory tree. Returns number of *files* removed (est.)."""
+    removed = 0
+    try:
+        if os.path.isdir(path) and not os.path.islink(path):
+            for dirpath, _, filenames in os.walk(path):
+                removed += len(filenames)
+            shutil.rmtree(path)
+            logger.info("Session cleanup: removed tree %s", path)
+        elif os.path.lexists(path):
+            os.remove(path)
+            removed = 1
+            logger.info("Session cleanup: removed %s", path)
+    except OSError as e:
+        logger.warning("Session cleanup failed %s: %s", path, e)
+    return removed
+
+
+def _remove_idle_unit(paths: list[str], cutoff: float) -> int:
+    """If the unit's newest mtime is older than cutoff, delete every path in it.
+
+    Re-checks mtime immediately before delete (narrows TOCTOU). Keeps the whole
+    unit if *any* member is still fresh — never splits SQLite sidecars.
+    """
+    paths = [p for p in paths if os.path.lexists(p)]
+    if not paths:
+        return 0
+    newest = _paths_newest_mtime(paths)
+    if newest is None or newest >= cutoff:
+        return 0
+    # Re-check right before mutating
+    newest2 = _paths_newest_mtime(paths)
+    if newest2 is None or newest2 >= cutoff:
+        return 0
+    removed = 0
+    for path in paths:
+        removed += _delete_path_unit(path)
+    return removed
+
+
+def _sqlite_unit_key(filename: str) -> str | None:
+    """Map ``id.db`` / ``id.db-wal`` / ``id.db-shm`` / ``id.db-journal`` → ``id.db``.
+
+    Returns None if the name is not a SQLite main DB or known sidecar.
+    """
+    if filename.endswith(".db"):
+        return filename
+    for tail in _SQLITE_SIDECAR_TAILS:
+        # e.g. foo.db-wal → foo.db
+        suf = ".db" + tail
+        if filename.endswith(suf):
+            return filename[: -len(tail)]
+    return None
+
+
+def _clean_conversation_dbs(conv_dir: str, cutoff: float) -> int:
+    """Expire idle agy conversation SQLite DBs as whole units (db+wal+shm)."""
+    if not os.path.isdir(conv_dir):
+        return 0
+    groups: dict[str, list[str]] = {}
+    loose: list[str] = []
+    try:
+        names = os.listdir(conv_dir)
+    except OSError as e:
+        logger.warning("Session cleanup list failed %s: %s", conv_dir, e)
+        return 0
+    for name in names:
+        path = os.path.join(conv_dir, name)
+        if os.path.isdir(path) and not os.path.islink(path):
+            # Unexpected subdir: treat as tree unit
+            loose.append(path)
+            continue
+        key = _sqlite_unit_key(name)
+        if key is not None:
+            groups.setdefault(key, []).append(path)
+        else:
+            loose.append(path)
+    removed = 0
+    for key, members in groups.items():
+        removed += _remove_idle_unit(members, cutoff)
+    for path in loose:
+        removed += _remove_idle_unit([path], cutoff)
+    return removed
+
+
+def _clean_child_units(parent: str, cutoff: float) -> int:
+    """Expire each direct child (file or directory tree) by its newest mtime."""
+    if not os.path.isdir(parent):
+        return 0
+    removed = 0
+    try:
+        names = os.listdir(parent)
+    except OSError as e:
+        logger.warning("Session cleanup list failed %s: %s", parent, e)
+        return 0
+    for name in names:
+        path = os.path.join(parent, name)
+        removed += _remove_idle_unit([path], cutoff)
+    return removed
+
+
+def _clean_grok_sessions(sessions_root: str, cutoff: float) -> int:
+    """Expire idle grok session trees: sessions/<cwd-key>/<session-id>/ as units.
+
+    Top-level index files (e.g. session_search.sqlite) are their own units.
+    Empty cwd-key dirs are pruned afterward.
+    """
+    if not os.path.isdir(sessions_root):
+        return 0
+    removed = 0
+    try:
+        names = os.listdir(sessions_root)
+    except OSError as e:
+        logger.warning("Session cleanup list failed %s: %s", sessions_root, e)
+        return 0
+    for name in names:
+        path = os.path.join(sessions_root, name)
+        if os.path.isfile(path) or os.path.islink(path):
+            removed += _remove_idle_unit([path], cutoff)
+            continue
+        if not os.path.isdir(path):
+            continue
+        # cwd-key bucket: expire each session-id child as a full tree
+        try:
+            children = os.listdir(path)
+        except OSError as e:
+            logger.warning("Session cleanup list failed %s: %s", path, e)
+            continue
+        for child in children:
+            child_path = os.path.join(path, child)
+            removed += _remove_idle_unit([child_path], cutoff)
+        try:
+            if not os.listdir(path):
+                os.rmdir(path)
+                logger.info("Session cleanup: removed empty dir %s", path)
+        except OSError:
+            pass
+    return removed
+
+
+def _clean_user_history(user_dir: str, cutoff: float) -> int:
+    """Unit-based dialogue history cleanup for one user session directory."""
+    removed = 0
+    removed += _clean_conversation_dbs(
+        os.path.join(user_dir, _HISTORY_CONVERSATIONS_REL), cutoff
+    )
+    removed += _clean_child_units(
+        os.path.join(user_dir, _HISTORY_BRAIN_REL), cutoff
+    )
+    removed += _clean_child_units(
+        os.path.join(user_dir, _HISTORY_KNOWLEDGE_REL), cutoff
+    )
+    removed += _clean_grok_sessions(
+        os.path.join(user_dir, _HISTORY_GROK_SESSIONS_REL), cutoff
+    )
+    return removed
+
+
+def _dir_has_any_file(root: str) -> bool:
+    if not os.path.isdir(root):
+        return False
+    try:
+        for dirpath, _, filenames in os.walk(root):
+            if filenames:
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def _clear_initialized_if_no_history(user_dir: str) -> bool:
+    """If no dialogue history left, drop .initialized so next turn starts fresh.
+
+    Avoids --continue against an empty/missing conversation after TTL cleanup.
+    """
+    for rel in _SESSION_HISTORY_REL_DIRS:
+        if _dir_has_any_file(os.path.join(user_dir, rel)):
+            return False
+    flag = os.path.join(user_dir, ".initialized")
+    if not os.path.exists(flag):
+        return False
+    try:
+        os.remove(flag)
+        logger.info(
+            "Session cleanup: cleared .initialized for %s (no history left)",
+            user_dir,
+        )
+        return True
+    except OSError as e:
+        logger.warning("Session cleanup: failed to clear .initialized %s: %s", flag, e)
+        return False
+
+
+def clean_session_data(
+    retention_days: int | None = None,
+    history_retention_days: int | None = None,
+) -> int:
+    """Remove old session artifacts under each user directory.
+
+    Two TTLs:
+      - Temps (default ``session_retention_days``, often 7d): file-level mtime
+        under images/files/.cache/scratch/logs/...
+      - Dialogue history (default ``history_retention_days``, 30d): **unit** idle
+        time = newest mtime in the unit. Units are:
+          * agy ``conversations``: each ``*.db`` + ``*.db-wal/shm/journal`` together
+          * agy ``brain`` / ``knowledge``: each top-level child tree/file
+          * grok ``sessions``: each ``<cwd>/<session-id>/`` tree; top-level indexes alone
+
+    Never splits a unit (prevents half-deleted SQLite DBs). Does **not** touch
+    prefs, auth links, or CLI install trees.
+
+    If a user's history dirs are fully empty after cleanup, removes
+    ``.initialized`` so the next message starts a new conversation.
+
+    Returns number of removed files (trees count as their file totals).
+    """
+    if retention_days is None:
+        retention_days = config.session_retention_days
+    if history_retention_days is None:
+        history_retention_days = config.history_retention_days
+    base = config.session_base_dir
+    if not os.path.isdir(base):
+        return 0
+    now = time.time()
+    temp_cutoff = now - max(int(retention_days), 0) * 86400
+    hist_cutoff = now - max(int(history_retention_days), 0) * 86400
+    removed = 0
+    try:
+        for name in os.listdir(base):
+            user_dir = os.path.join(base, name)
+            if not os.path.isdir(user_dir):
+                continue
+            for rel in _SESSION_TEMP_REL_DIRS:
+                removed += _remove_old_files_under(
+                    os.path.join(user_dir, rel), temp_cutoff
+                )
+            removed += _clean_user_history(user_dir, hist_cutoff)
+            _clear_initialized_if_no_history(user_dir)
+    except OSError as e:
+        logger.error("Session data cleanup error: %s", e)
+    return removed
+
+
+def clean_session_media(retention_days: int | None = None) -> int:
+    """Backward-compatible alias for :func:`clean_session_data` (temps + history)."""
+    return clean_session_data(retention_days=retention_days)
+
+
+def split_message_chunks(text: str, limit: int | None = None) -> list[str]:
+    """Split a long reply into chunks under limit characters (prefer newlines).
+
+    Cuts by position only — no rstrip/lstrip at boundaries — so
+    ''.join(chunks) always equals the original text.
+    """
+    if limit is None:
+        limit = config.message_chunk_chars
+    if limit <= 0:
+        return [text or ""]
+    text = text or ""
+    if len(text) <= limit:
+        return [text]
+
+    chunks: list[str] = []
+    rest = text
+    while rest:
+        if len(rest) <= limit:
+            chunks.append(rest)
+            break
+        window = rest[:limit]
+        # Prefer break at newline, then space; never cut at <=0 (would infinite-loop)
+        cut = window.rfind("\n")
+        if cut <= 0 or cut < limit // 3:
+            cut = window.rfind(" ")
+        if cut <= 0 or cut < limit // 3:
+            cut = limit
+        chunks.append(rest[:cut])
+        rest = rest[cut:]
+    # Drop pure-empty pieces only (should not happen with cut > 0)
+    return [c for c in chunks if c != ""] or [""]
+
+
+async def terminate_process(process, graceful: bool = True) -> None:
+    """Terminate a subprocess with Unix process-group or Windows direct kill.
+
+    graceful: SIGTERM → 2s wait → SIGKILL (Unix); kill() (Windows).
+    Non-graceful: SIGKILL immediately (Unix); kill() (Windows).
+    """
+    if not process or not process.pid:
+        return
+    try:
+        if hasattr(os, "getpgid") and hasattr(os, "killpg"):
+            pgid = os.getpgid(process.pid)
+            if graceful:
+                os.killpg(pgid, signal.SIGTERM)
+                logger.info("Sent SIGTERM to process group %s for graceful lock release", pgid)
+                for _ in range(20):
+                    if process.returncode is not None:
+                        break
+                    await asyncio.sleep(0.1)
+                if process.returncode is None:
+                    os.killpg(pgid, signal.SIGKILL)
+                    logger.info("Sent SIGKILL to process group %s after grace period", pgid)
+            else:
+                os.killpg(pgid, signal.SIGKILL)
+        else:
+            # Windows: no process groups, kill directly
+            process.kill()
+            logger.info("Killed process %s directly (non-Unix)", process.pid)
+    except (ProcessLookupError, PermissionError, OSError) as e:
+        logger.warning("Failed to terminate process: %s", e)
+    try:
+        await process.wait()
+    except Exception:
+        pass