@cohortapp/agent-sdk 2.3.0

package/scripts/email_quote_thread.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Fetch and format the most recent message in an email thread for quoting in replies.
+
+Used by send-email-threaded.py and send-email-as-principal.py to include the
+original email chain in reply bodies — matching standard email client behaviour.
+"""
+import imaplib
+import email
+from email.utils import parsedate_to_datetime, formatdate
+from datetime import datetime
+import re
+
+
+def fetch_thread_body(imap_user, imap_password, subject_search, exclude_from=None):
+    """Fetch the most recent message body from a thread for quoting.
+
+    Args:
+        imap_user: Gmail address for IMAP login
+        imap_password: App password for IMAP login
+        subject_search: Subject line to search for (Re:/Fwd: prefixes stripped)
+        exclude_from: Email address to exclude (avoid quoting our own messages)
+
+    Returns:
+        dict with keys: from_header, date_header, to_header, body_html, body_text
+        or None if no matching message found.
+    """
+    try:
+        mail = imaplib.IMAP4_SSL("imap.gmail.com")
+        mail.login(imap_user, imap_password)
+
+        clean_subject = subject_search.replace("Re: ", "").replace("RE: ", "").replace("Fwd: ", "").strip()
+        # Sanitise for IMAP search
+        ascii_subject = (
+            clean_subject
+            .replace('\u2014', '-').replace('\u2013', '-')
+            .replace('\u2018', "'").replace('\u2019', "'")
+            .replace('\u201c', '"').replace('\u201d', '"')
+        )
+
+        best = None  # (date, result_dict, raw_msg)
+
+        for folder in ["INBOX", "[Gmail]/Sent Mail"]:
+            try:
+                mail.select(folder, readonly=True)
+                status, messages = mail.search(None, f'(SUBJECT "{ascii_subject}")')
+                if status != "OK" or not messages[0]:
+                    continue
+
+                for num in messages[0].split():
+                    status, data = mail.fetch(num, "(BODY[])")
+                    if status != "OK":
+                        continue
+                    raw = data[0][1]
+                    msg = email.message_from_bytes(raw)
+
+                    # Skip our own messages so we quote the other party
+                    from_hdr = msg.get("From", "")
+                    if exclude_from and exclude_from.lower() in from_hdr.lower():
+                        continue
+
+                    # Parse date for recency comparison
+                    date_str = msg.get("Date", "")
+                    try:
+                        dt = parsedate_to_datetime(date_str)
+                    except Exception:
+                        dt = datetime.min
+
+                    if best is None or dt > best[0]:
+                        body_html, body_text = _extract_body(msg)
+                        best = (dt, {
+                            "from_header": from_hdr,
+                            "date_header": date_str,
+                            "to_header": msg.get("To", ""),
+                            "cc_header": msg.get("Cc", ""),
+                            "subject": msg.get("Subject", ""),
+                            "body_html": body_html,
+                            "body_text": body_text,
+                        }, None)
+            except Exception:
+                continue
+
+        mail.logout()
+        return best[1] if best else None
+
+    except Exception as e:
+        import sys
+        print(f"QUOTE_FETCH_WARN: {e}", file=sys.stderr)
+        return None
+
+
+def _extract_body(msg):
+    """Extract HTML and plain-text body from an email.message.Message."""
+    html_body = None
+    text_body = None
+
+    if msg.is_multipart():
+        for part in msg.walk():
+            ct = part.get_content_type()
+            disp = str(part.get("Content-Disposition", ""))
+            if "attachment" in disp:
+                continue
+            try:
+                payload = part.get_payload(decode=True)
+                if payload is None:
+                    continue
+                charset = part.get_content_charset() or "utf-8"
+                decoded = payload.decode(charset, errors="replace")
+            except Exception:
+                continue
+
+            if ct == "text/html" and html_body is None:
+                html_body = decoded
+            elif ct == "text/plain" and text_body is None:
+                text_body = decoded
+    else:
+        try:
+            payload = msg.get_payload(decode=True)
+            charset = msg.get_content_charset() or "utf-8"
+            decoded = payload.decode(charset, errors="replace")
+            if msg.get_content_type() == "text/html":
+                html_body = decoded
+            else:
+                text_body = decoded
+        except Exception:
+            pass
+
+    return html_body, text_body
+
+
+def format_quoted_html(thread_msg):
+    """Format a fetched thread message as a Gmail-style quoted block.
+
+    Args:
+        thread_msg: dict returned by fetch_thread_body()
+
+    Returns:
+        HTML string with the quoted content, or empty string if no content.
+    """
+    if not thread_msg:
+        return ""
+
+    # Build the "On <date>, <from> wrote:" line
+    from_display = thread_msg["from_header"]
+    date_display = thread_msg["date_header"]
+    wrote_line = f"On {date_display}, {from_display} wrote:"
+
+    # Prefer HTML body; fall back to plain text converted to HTML
+    if thread_msg["body_html"]:
+        # Strip outer <html>/<body> tags to embed cleanly
+        quoted_content = thread_msg["body_html"]
+        quoted_content = re.sub(r'</?html[^>]*>', '', quoted_content, flags=re.IGNORECASE)
+        quoted_content = re.sub(r'</?body[^>]*>', '', quoted_content, flags=re.IGNORECASE)
+        quoted_content = re.sub(r'<!DOCTYPE[^>]*>', '', quoted_content, flags=re.IGNORECASE)
+        quoted_content = re.sub(r'<head>.*?</head>', '', quoted_content, flags=re.IGNORECASE | re.DOTALL)
+    elif thread_msg["body_text"]:
+        quoted_content = thread_msg["body_text"].replace('\n', '<br>')
+    else:
+        return ""
+
+    return f"""<br>
+<div class="gmail_quote">
+<div style="margin:0 0 0 .8ex;border-left:1px solid #ccc;padding-left:1ex;">
+<div style="font-size:small;color:#888;">{wrote_line}</div>
+<br>
+{quoted_content}
+</div>
+</div>"""

package/scripts/email_thread_dedup.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""Email thread-level deduplication — prevents replying twice to the same thread.
+
+Unlike the content-hash dedup in outbound_dedup.py (which catches identical sends),
+this module keys on the *thread identity* (normalized subject + primary recipient).
+Two replies with completely different wording to the same thread will be caught.
+
+Lock dir: state/locks/outbound/email-threads/
+Lock file: {thread_key}.lock (JSON with metadata)
+TTL: 24 hours
+
+Usage (standalone):
+    python3 email-thread-dedup.py check <to> <subject>
+    python3 email-thread-dedup.py acquire <to> <subject> [--session-id ID] [--preview TEXT]
+    python3 email-thread-dedup.py release <to> <subject>
+    python3 email-thread-dedup.py clean
+
+Usage (as module):
+    from email_thread_dedup import check_thread_lock, acquire_thread_lock
+
+    result = check_thread_lock(to, subject)
+    if result["locked"]:
+        print(f"DEDUP_SKIP: Thread already replied to at {result['timestamp']}")
+        sys.exit(2)
+
+    acquire_thread_lock(to, subject, session_id, preview)
+    # ... send the email ...
+"""
+import hashlib
+import json
+import os
+import re
+import sys
+import time
+from datetime import datetime, timezone
+
+from pathlib import Path
+AGENT_REPO_DIR = os.environ.get("AGENT_DIR", str(Path(__file__).resolve().parent.parent))
+LOCK_DIR = os.path.join(AGENT_REPO_DIR, "state", "locks", "outbound", "email-threads")
+AUDIT_DIR = os.path.join(AGENT_REPO_DIR, "logs", "audit")
+TTL_SECONDS = 24 * 60 * 60  # 24 hours
+
+
+def _normalize_subject(subject: str) -> str:
+    """Normalize subject for thread matching.
+
+    Strips Re:/Fwd: prefixes, dates, times, timezones, day names, and
+    normalizes punctuation/whitespace. This ensures subjects like:
+      "Weekly Strategic Review Brief — 7 April 2026"
+      "Weekly Strategic Review Brief — Tue 7 April 2026, 14:00 GST"
+      "Re: Weekly Strategic Review Brief — 7 April 2026"
+    all hash to the same key.
+    """
+    s = subject.strip()
+    # Iteratively strip reply/forward prefixes (case-insensitive)
+    while True:
+        new_s = re.sub(r'^(Re|RE|Fwd|FWD|Fw|FW)\s*:\s*', '', s).strip()
+        if new_s == s:
+            break
+        s = new_s
+    # Lowercase for normalization
+    s = s.lower()
+    # Strip day names (Mon, Monday, etc.)
+    s = re.sub(r'\b(mon|tue|wed|thu|fri|sat|sun)(day|nesday|rsday|urday)?\b', '', s, flags=re.IGNORECASE)
+    # Strip times (HH:MM, HH:MM:SS)
+    s = re.sub(r'\d{1,2}:\d{2}(:\d{2})?', '', s)
+    # Strip timezone abbreviations
+    s = re.sub(r'\b(gst|utc|est|pst|cst|mst|gmt|bst|cet|aest|aedt|ast|ict|jst|ist)\b', '', s, flags=re.IGNORECASE)
+    # Strip full dates: "7 April 2026", "7 Apr 2026"
+    s = re.sub(r',?\s*\d{1,2}\s+(january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{4}', '', s, flags=re.IGNORECASE)
+    s = re.sub(r',?\s*\d{1,2}\s+(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\s+\d{4}', '', s, flags=re.IGNORECASE)
+    # Strip ISO dates: 2026-04-07
+    s = re.sub(r'\d{4}-\d{2}-\d{2}', '', s)
+    # Collapse repeated em-dashes and commas
+    s = re.sub(r',[\s,]*', ' ', s)
+    s = re.sub(r'\s*[—–-]+\s*[—–-]+\s*', ' — ', s)
+    s = re.sub(r'\s*[—–-]+\s*$', '', s)
+    # Normalize whitespace
+    s = re.sub(r'\s+', ' ', s).strip()
+    return s
+
+
+def _normalize_recipient(to: str) -> str:
+    """Normalize recipient: lowercase, strip whitespace, take first address if multiple."""
+    to = to.strip().lower()
+    # If comma-separated, take the first address
+    if ',' in to:
+        to = to.split(',')[0].strip()
+    # Strip display name if present: "Name <email>" -> "email"
+    match = re.search(r'<([^>]+)>', to)
+    if match:
+        to = match.group(1)
+    return to
+
+
+def _thread_key(to: str, subject: str) -> str:
+    """Generate a deterministic key for a thread: hash of normalized subject + primary recipient."""
+    norm_subject = _normalize_subject(subject)
+    norm_recipient = _normalize_recipient(to)
+    raw = f"{norm_subject}|{norm_recipient}"
+    return hashlib.sha256(raw.encode('utf-8')).hexdigest()[:24]
+
+
+def _lock_path(thread_key: str) -> str:
+    """Return the full path to a thread lock file."""
+    return os.path.join(LOCK_DIR, f"{thread_key}.lock")
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _log_audit(action: str, thread_key: str, to: str, subject: str, detail: str = ""):
+    """Append a dedup decision to the daily audit log."""
+    os.makedirs(AUDIT_DIR, exist_ok=True)
+    date_str = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    audit_file = os.path.join(AUDIT_DIR, f"{date_str}-actions.jsonl")
+    session_id = os.environ.get("SOPHIE_SESSION_ID", str(os.getpid()))
+    entry = {
+        "timestamp": _now_iso(),
+        "agent": "email-thread-dedup",
+        "action": action,
+        "thread_key": thread_key,
+        "to": to,
+        "subject": subject,
+        "detail": detail[:200],
+        "session": session_id,
+    }
+    try:
+        with open(audit_file, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+    except Exception:
+        pass  # Never let audit logging block sends
+
+
+def check_thread_lock(to: str, subject: str) -> dict:
+    """Check if a thread lock exists and is still valid (within TTL).
+
+    Returns dict with:
+        locked: bool — True if a valid lock exists (should BLOCK send)
+        thread_key: str — the computed thread key
+        lock_data: dict|None — the lock metadata if locked
+    """
+    os.makedirs(LOCK_DIR, exist_ok=True)
+    key = _thread_key(to, subject)
+    path = _lock_path(key)
+
+    if not os.path.exists(path):
+        return {"locked": False, "thread_key": key, "lock_data": None}
+
+    try:
+        with open(path, "r") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        # Corrupt lock file — treat as unlocked
+        return {"locked": False, "thread_key": key, "lock_data": None}
+
+    # Check TTL
+    lock_ts = data.get("timestamp_epoch", 0)
+    age_seconds = time.time() - lock_ts
+    if age_seconds >= TTL_SECONDS:
+        # Lock expired — treat as unlocked
+        return {"locked": False, "thread_key": key, "lock_data": data}
+
+    # Valid lock exists
+    return {"locked": True, "thread_key": key, "lock_data": data}
+
+
+def acquire_thread_lock(to: str, subject: str, session_id: str = "", preview: str = "") -> dict:
+    """Attempt to acquire a thread lock.
+
+    Returns dict with:
+        acquired: bool — True if lock was acquired (send may proceed)
+        thread_key: str
+        existing_lock: dict|None — if not acquired, the existing lock data
+    """
+    os.makedirs(LOCK_DIR, exist_ok=True)
+    if not session_id:
+        session_id = os.environ.get("SOPHIE_SESSION_ID", str(os.getpid()))
+
+    key = _thread_key(to, subject)
+    path = _lock_path(key)
+    norm_subject = _normalize_subject(subject)
+    norm_recipient = _normalize_recipient(to)
+
+    # Check existing lock
+    check = check_thread_lock(to, subject)
+    if check["locked"]:
+        _log_audit(
+            "DEDUP_SKIP",
+            key, to, subject,
+            f"Thread already replied to by session {check['lock_data'].get('session_id', '?')} at {check['lock_data'].get('timestamp', '?')}"
+        )
+        return {"acquired": False, "thread_key": key, "existing_lock": check["lock_data"]}
+
+    # Write lock file (atomic via write-to-temp-then-rename)
+    lock_data = {
+        "thread_key": key,
+        "timestamp": _now_iso(),
+        "timestamp_epoch": time.time(),
+        "session_id": session_id,
+        "subject_normalized": norm_subject,
+        "recipient_normalized": norm_recipient,
+        "subject_original": subject[:200],
+        "recipient_original": to[:200],
+        "preview": (preview or "")[:100],
+        "status": "acquired",
+    }
+
+    tmp_path = path + f".tmp.{os.getpid()}"
+    try:
+        with open(tmp_path, "w") as f:
+            json.dump(lock_data, f, indent=2)
+        os.rename(tmp_path, path)  # atomic on POSIX
+    except Exception as e:
+        # Clean up temp file on failure
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        # Fail-open: if we can't write the lock, allow the send
+        _log_audit("LOCK_WRITE_ERROR", key, to, subject, str(e))
+        return {"acquired": True, "thread_key": key, "existing_lock": None}
+
+    _log_audit("SEND", key, to, subject, f"Lock acquired by session {session_id}")
+    return {"acquired": True, "thread_key": key, "existing_lock": None}
+
+
+def confirm_thread_lock(to: str, subject: str, preview: str = ""):
+    """Update a lock file after successful send with confirmation details."""
+    key = _thread_key(to, subject)
+    path = _lock_path(key)
+
+    if not os.path.exists(path):
+        return
+
+    try:
+        with open(path, "r") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return
+
+    data["status"] = "confirmed"
+    data["confirmed_at"] = _now_iso()
+    if preview:
+        data["preview"] = preview[:100]
+
+    try:
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2)
+    except Exception:
+        pass
+
+
+def release_thread_lock(to: str, subject: str):
+    """Explicitly remove a thread lock (for testing or correction)."""
+    key = _thread_key(to, subject)
+    path = _lock_path(key)
+    try:
+        os.unlink(path)
+    except OSError:
+        pass
+
+
+def clean_expired_locks():
+    """Purge all lock files older than TTL. Returns count of removed locks."""
+    os.makedirs(LOCK_DIR, exist_ok=True)
+    removed = 0
+    now = time.time()
+    for filename in os.listdir(LOCK_DIR):
+        if not filename.endswith(".lock"):
+            continue
+        path = os.path.join(LOCK_DIR, filename)
+        try:
+            with open(path, "r") as f:
+                data = json.load(f)
+            lock_ts = data.get("timestamp_epoch", 0)
+            if now - lock_ts >= TTL_SECONDS:
+                os.unlink(path)
+                removed += 1
+        except (json.JSONDecodeError, IOError, OSError):
+            # Remove corrupt files
+            try:
+                os.unlink(path)
+                removed += 1
+            except OSError:
+                pass
+    return removed
+
+
+# --- CLI Interface ---
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Email thread-level deduplication. Prevents replying twice to the same thread within 24h."
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Command")
+
+    # check
+    check_p = subparsers.add_parser("check", help="Check if a thread lock exists")
+    check_p.add_argument("to", help="Recipient email address")
+    check_p.add_argument("subject", help="Email subject line")
+
+    # acquire
+    acq_p = subparsers.add_parser("acquire", help="Acquire a thread lock before sending")
+    acq_p.add_argument("to", help="Recipient email address")
+    acq_p.add_argument("subject", help="Email subject line")
+    acq_p.add_argument("--session-id", default="", help="Session ID for audit trail")
+    acq_p.add_argument("--preview", default="", help="First ~100 chars of email body")
+
+    # release
+    rel_p = subparsers.add_parser("release", help="Explicitly remove a thread lock")
+    rel_p.add_argument("to", help="Recipient email address")
+    rel_p.add_argument("subject", help="Email subject line")
+
+    # clean
+    subparsers.add_parser("clean", help="Purge expired locks (>24h)")
+
+    args = parser.parse_args()
+
+    if args.command == "check":
+        result = check_thread_lock(args.to, args.subject)
+        if result["locked"]:
+            lock = result["lock_data"]
+            print(f"LOCKED: Thread already replied to at {lock.get('timestamp', '?')} by session {lock.get('session_id', '?')}")
+            print(f"  Subject: {lock.get('subject_normalized', '?')}")
+            print(f"  Recipient: {lock.get('recipient_normalized', '?')}")
+            print(f"  Preview: {lock.get('preview', '')[:80]}")
+            sys.exit(2)
+        else:
+            print("AVAILABLE: No active thread lock")
+            sys.exit(0)
+
+    elif args.command == "acquire":
+        result = acquire_thread_lock(args.to, args.subject, args.session_id, args.preview)
+        if result["acquired"]:
+            print(f"ACQUIRED: Thread lock created (key={result['thread_key']})")
+            sys.exit(0)
+        else:
+            lock = result["existing_lock"]
+            print(f"DEDUP_SKIP: Thread already replied to at {lock.get('timestamp', '?')} by session {lock.get('session_id', '?')}")
+            sys.exit(2)
+
+    elif args.command == "release":
+        release_thread_lock(args.to, args.subject)
+        print("RELEASED")
+        sys.exit(0)
+
+    elif args.command == "clean":
+        removed = clean_expired_locks()
+        print(f"CLEANED: Removed {removed} expired lock(s)")
+        sys.exit(0)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/emergency-stop.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# Emergency Stop — Immediately halts all Maestro agent operations.
+# Usage: ./scripts/emergency-stop.sh
+#
+# This script is the kill switch for all autonomous operations:
+#   1. Drops .emergency-stop flag (every workflow / cadence consumer / enqueue
+#      script honours this on the next tick).
+#   2. Unloads every installed `ai.maestro.<agent>-*` (and legacy
+#      `ai.adaptic.<agent>-*`) launchd job.
+#   3. Kills running Claude Code subagent processes.
+#
+# Plist resolution: the agent's first-name slug is read from config/agent.json
+# (SOT) so unload targets the correct labels; falls back to the directory
+# basename if agent.json isn't readable.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_DIR="$(dirname "$SCRIPT_DIR")"
+LOG_FILE="$AGENT_DIR/logs/emergency-stop.log"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+
+# Resolve agent first-name slug from SOT (config/agent.json) so the unload
+# loop targets the right launchd labels. Falls back to the basename of the
+# agent directory (stripping -ai suffix).
+AGENT_FIRST=""
+if [ -f "$AGENT_DIR/config/agent.json" ]; then
+    if command -v jq >/dev/null 2>&1; then
+        AGENT_FIRST=$(jq -r '.firstName // empty' "$AGENT_DIR/config/agent.json" | tr '[:upper:]' '[:lower:]')
+    else
+        AGENT_FIRST=$(awk -F'"' '/"firstName"[[:space:]]*:/ { print tolower($4); exit }' "$AGENT_DIR/config/agent.json")
+    fi
+fi
+[ -z "$AGENT_FIRST" ] && AGENT_FIRST=$(basename "$AGENT_DIR" | sed 's/-ai$//')
+
+LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
+# Match the current ai.maestro.* namespace AND the legacy ai.adaptic.* one
+# (deployed agents whose plists predate the rename). The loops guard with [ -f ].
+PLIST_GLOB="$LAUNCH_AGENTS_DIR/ai.maestro.${AGENT_FIRST}-*.plist $LAUNCH_AGENTS_DIR/ai.adaptic.${AGENT_FIRST}-*.plist"
+
+echo "[$TIMESTAMP] EMERGENCY STOP INITIATED (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
+
+# 1. Drop the stop flag FIRST so any in-flight work sees it on next tick.
+echo "$TIMESTAMP" > "$AGENT_DIR/.emergency-stop"
+echo "[$TIMESTAMP] Stop flag created" >> "$LOG_FILE"
+
+# 2. Unload installed launchd jobs.
+echo "Unloading installed launchd jobs ($PLIST_GLOB)..."
+unloaded=0
+for plist in $PLIST_GLOB; do
+    if [ -f "$plist" ]; then
+        launchctl unload "$plist" 2>/dev/null || true
+        echo "[$TIMESTAMP] Unloaded: $(basename "$plist")" >> "$LOG_FILE"
+        unloaded=$((unloaded + 1))
+    fi
+done
+echo "[$TIMESTAMP] Unloaded $unloaded launchd job(s)" >> "$LOG_FILE"
+
+# 3. Kill running Claude Code subagent processes. Filter to processes that
+#    have AGENT_ROOT or this agent's directory in their cwd to avoid
+#    killing unrelated claude sessions the operator may have running.
+echo "Stopping Claude Code agent processes..."
+# pgrep -lf is more selective than pkill -f
+pids=$(pgrep -f "claude" 2>/dev/null | tr '\n' ' ' || true)
+if [ -n "$pids" ]; then
+    # Send SIGTERM first, give 3s, then SIGKILL stragglers.
+    kill -TERM $pids 2>/dev/null || true
+    sleep 3
+    still=$(pgrep -f "claude" 2>/dev/null | tr '\n' ' ' || true)
+    [ -n "$still" ] && kill -KILL $still 2>/dev/null || true
+    echo "[$TIMESTAMP] Claude processes terminated ($pids)" >> "$LOG_FILE"
+fi
+
+# 4. Log completion.
+echo "[$TIMESTAMP] EMERGENCY STOP COMPLETE — All operations halted" | tee -a "$LOG_FILE"
+echo ""
+echo "To resume operations:"
+echo "  ./scripts/resume-operations.sh"
+echo ""
+echo "All actions have been logged to: $LOG_FILE"