checkin_queue.py

#!/usr/bin/env python3
"""
tools/checkin/checkin_queue.py — Pending check-in queue for webchat-only users.

When the agency engine or silence detector flags a user for a check-in but
there's no outbound channel (no email, no phone, no Telegram), the check-in
is queued here instead of being dropped.

When the user next visits webchat (or voice, or any channel), the pending
check-in is retrieved and woven into Kith's first response as warmth —
not as a system message.

Storage: users/{id}/pending_checkins.jsonl (one JSON object per line)

Usage:
    from checkin_queue import queue_checkin, get_pending, mark_delivered

    queue_checkin("ruby", reason="3 days silent, emotionally heavy last contact",
                  suggested_tone="gentle", suggested_opener="I was thinking about you")

    pending = get_pending("ruby")
    # => [{"id": "...", "reason": "...", ...}]

    mark_delivered("ruby", pending[0]["id"])
"""

import json
import os
import uuid
from datetime import datetime, timezone
from pathlib import Path

WORKSPACE = Path(os.environ.get("CHECKIN_WORKSPACE", str(Path.home() / ".checkin-queue")))
USERS_DIR = WORKSPACE / "users"
LOG_PATH = WORKSPACE / "checkin_queue.log"


def _queue_path(user_id: str) -> Path:
    return USERS_DIR / user_id / "pending_checkins.jsonl"


def queue_checkin(
    user_id: str,
    reason: str,
    suggested_tone: str = "warm",
    suggested_opener: str = "",
    emotional_weight: str = "neutral",
    suggested_approach: str = "",
    source: str = "check_silence",
) -> str:
    """Store a pending check-in for a user.

    Returns the check-in ID.
    """
    checkin_id = f"ci-{uuid.uuid4().hex[:8]}"
    entry = {
        "id": checkin_id,
        "user_id": user_id,
        "reason": reason,
        "suggested_tone": suggested_tone,
        "suggested_opener": suggested_opener,
        "emotional_weight": emotional_weight,
        "suggested_approach": suggested_approach,
        "source": source,
        "queued_at": datetime.now(timezone.utc).isoformat(),
        "delivered": False,
        "delivered_at": None,
        "delivered_channel": None,
    }

    queue_file = _queue_path(user_id)
    queue_file.parent.mkdir(parents=True, exist_ok=True)

    with open(queue_file, "a") as f:
        f.write(json.dumps(entry) + "\n")

    # Audit log
    _log(f"QUEUED {checkin_id} for {user_id}: {reason[:120]}")

    return checkin_id


def get_pending(user_id: str) -> list[dict]:
    """Return all undelivered check-ins for a user, oldest first."""
    queue_file = _queue_path(user_id)
    if not queue_file.exists():
        return []

    pending = []
    for line in queue_file.read_text().splitlines():
        line = line.strip()
        if not line:
            continue
        try:
            entry = json.loads(line)
            if not entry.get("delivered", False):
                pending.append(entry)
        except json.JSONDecodeError:
            continue

    return pending


def mark_delivered(user_id: str, checkin_id: str, channel: str = "webchat") -> bool:
    """Mark a specific check-in as delivered. Rewrites the JSONL file.

    Returns True if the check-in was found and marked.
    """
    queue_file = _queue_path(user_id)
    if not queue_file.exists():
        return False

    lines = queue_file.read_text().splitlines()
    updated = []
    found = False

    for line in lines:
        line = line.strip()
        if not line:
            continue
        try:
            entry = json.loads(line)
            if entry.get("id") == checkin_id and not entry.get("delivered"):
                entry["delivered"] = True
                entry["delivered_at"] = datetime.now(timezone.utc).isoformat()
                entry["delivered_channel"] = channel
                found = True
                _log(f"DELIVERED {checkin_id} for {user_id} via {channel}")
            updated.append(json.dumps(entry))
        except json.JSONDecodeError:
            updated.append(line)

    queue_file.write_text("\n".join(updated) + "\n" if updated else "")
    return found


def mark_all_delivered(user_id: str, channel: str = "webchat") -> int:
    """Mark all pending check-ins for a user as delivered.

    Returns the count of check-ins marked.
    """
    pending = get_pending(user_id)
    count = 0
    for ci in pending:
        if mark_delivered(user_id, ci["id"], channel):
            count += 1
    return count


def format_for_context(pending: list[dict]) -> str:
    """Format pending check-ins into a context block for injection into
    Kith's first response. Written as warmth cues, not system directives.

    Returns empty string if no pending check-ins.
    """
    if not pending:
        return ""

    parts = []
    parts.append(
        "--- PENDING CHECK-IN (warmth, not system message) ---"
    )
    parts.append(
        "You had been thinking about this person. They were flagged for a "
        "check-in while they were away, but you had no way to reach them. "
        "Now they're here. Weave this naturally into your warmth — "
        "\"I was thinking about you\" or \"I'm glad you're here\" — "
        "not as a notification. Never mention the check-in system."
    )

    for ci in pending:
        reason = ci.get("reason", "")
        tone = ci.get("suggested_tone", "warm")
        opener = ci.get("suggested_opener", "")
        approach = ci.get("suggested_approach", "")
        weight = ci.get("emotional_weight", "neutral")
        queued = ci.get("queued_at", "")[:10]

        parts.append(f"  Why: {reason}")
        if approach:
            parts.append(f"  Approach: {approach}")
        if opener:
            parts.append(f"  Suggested opener thread: {opener}")
        parts.append(f"  Tone: {tone} | Weight: {weight} | Queued: {queued}")

    parts.append("--- END PENDING CHECK-IN ---")
    return "\n".join(parts)


def has_outbound_channel(user_id: str) -> bool:
    """Check whether a user has any outbound channel (email, sms, telegram).

    Returns False if the user is webchat-only (Kith cannot initiate contact).
    """
    ident_path = USERS_DIR / user_id / "identity.json"
    if not ident_path.exists():
        return False

    try:
        ident = json.loads(ident_path.read_text())
    except (json.JSONDecodeError, OSError):
        return False

    channels = ident.get("channels", {})

    # Check email
    emails = channels.get("email", [])
    if isinstance(emails, list) and emails:
        return True

    # Check sms
    sms = channels.get("sms", [])
    if isinstance(sms, list) and sms:
        return True

    # Check telegram
    telegram = channels.get("telegram", [])
    if isinstance(telegram, list) and telegram:
        return True

    return False


def get_session_count(user_id: str) -> int:
    """Count the number of webchat sessions for a user (approximate).

    Counts unique session IDs in interactions.log.
    """
    log_path = USERS_DIR / user_id / "interactions.log"
    if not log_path.exists():
        return 0

    sessions = set()
    for line in log_path.read_text().splitlines():
        line = line.strip()
        if not line:
            continue
        try:
            entry = json.loads(line)
            sid = entry.get("session_id", entry.get("session", ""))
            if sid:
                sessions.add(sid)
        except json.JSONDecodeError:
            continue

    return len(sessions)


def should_ask_contact_info(user_id: str) -> bool:
    """Determine if Kith should gently ask for contact info this session.

    Conditions (all must be true):
    - User has no outbound channel
    - User has 3+ webchat sessions
    - User has been flagged for at least one check-in
    - We haven't asked before (tracked in identity.json)
    """
    if has_outbound_channel(user_id):
        return False

    if get_session_count(user_id) < 3:
        return False

    if not get_pending(user_id) and not _has_past_checkins(user_id):
        return False

    # Check if we've already asked
    ident_path = USERS_DIR / user_id / "identity.json"
    if ident_path.exists():
        try:
            ident = json.loads(ident_path.read_text())
            if ident.get("contact_info_asked"):
                return False
        except (json.JSONDecodeError, OSError):
            pass

    return True


def mark_contact_info_asked(user_id: str):
    """Record that we've asked this user for contact info (once is enough)."""
    ident_path = USERS_DIR / user_id / "identity.json"
    if not ident_path.exists():
        return

    try:
        ident = json.loads(ident_path.read_text())
        ident["contact_info_asked"] = datetime.now(timezone.utc).isoformat()
        ident_path.write_text(json.dumps(ident, indent=2) + "\n")
    except (json.JSONDecodeError, OSError):
        pass


def _has_past_checkins(user_id: str) -> bool:
    """Check if there are any check-ins (delivered or not) in the queue file."""
    queue_file = _queue_path(user_id)
    if not queue_file.exists():
        return False
    content = queue_file.read_text().strip()
    return bool(content)


def format_contact_ask_context() -> str:
    """Return a context hint for Kith to naturally ask for contact info."""
    return (
        "--- CONTACT INFO OPPORTUNITY ---\n"
        "This person has been webchat-only for several sessions and you've "
        "wanted to check on them before but had no way to reach out. "
        "If it fits naturally in the conversation — not forced, not as a first thing — "
        "you might warmly mention that you'd love to be able to reach them sometimes. "
        "Something like: \"I'd love to be able to check in on you sometimes — "
        "is there an email or phone number I could use?\" "
        "Only if the moment feels right. Once. Don't push.\n"
        "--- END CONTACT INFO OPPORTUNITY ---"
    )


def _log(message: str):
    """Append to the check-in queue audit log."""
    now_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S CT")
    try:
        with open(LOG_PATH, "a") as f:
            f.write(f"{now_str}  {message}\n")
    except OSError:
        pass


if __name__ == "__main__":
    import sys

    if len(sys.argv) < 2:
        print("Usage:")
        print("  python3 checkin_queue.py pending <user_id>")
        print("  python3 checkin_queue.py queue <user_id> <reason>")
        print("  python3 checkin_queue.py deliver <user_id> <checkin_id>")
        sys.exit(1)

    cmd = sys.argv[1]

    if cmd == "pending" and len(sys.argv) >= 3:
        user_id = sys.argv[2]
        pending = get_pending(user_id)
        if pending:
            print(f"{len(pending)} pending check-in(s) for {user_id}:")
            for ci in pending:
                print(f"  {ci['id']}: {ci['reason'][:80]} (queued {ci['queued_at'][:10]})")
        else:
            print(f"No pending check-ins for {user_id}")

    elif cmd == "queue" and len(sys.argv) >= 4:
        user_id = sys.argv[2]
        reason = " ".join(sys.argv[3:])
        cid = queue_checkin(user_id, reason)
        print(f"Queued: {cid}")

    elif cmd == "deliver" and len(sys.argv) >= 4:
        user_id = sys.argv[2]
        checkin_id = sys.argv[3]
        if mark_delivered(user_id, checkin_id):
            print(f"Marked {checkin_id} as delivered")
        else:
            print(f"Check-in {checkin_id} not found or already delivered")

    else:
        print(f"Unknown command: {cmd}")
        sys.exit(1)