@cohortapp/agent-sdk 2.3.0

package/scripts/send-email-with-attachment.py

@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+"""Send an HTML email with file attachment via Gmail SMTP.
+
+Usage: python3 send-email-with-attachment.py <to> <subject> <body> [--cc email] [--attachment path] [--reply-to-subject "original subject"] [--in-reply-to "<message-id>"]
+
+Sends as the running agent (identity from config/agent.json) with branded signature block.
+Supports PNG, PDF, and other file attachments via MIME.
+"""
+import sys
+import os
+import imaplib
+import email
+import smtplib
+import mimetypes
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from email.mime.base import MIMEBase
+from email.mime.image import MIMEImage
+from email.mime.application import MIMEApplication
+from email import encoders
+from email.utils import formatdate
+from pathlib import Path
+
+# Outbound dedup — fail-open if module not available
+try:
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    from outbound_dedup import acquire_email_lock, confirm_email_lock
+    _DEDUP_AVAILABLE = True
+except ImportError:
+    _DEDUP_AVAILABLE = False
+
+# LLM-based dedup — replaces old subject+recipient lock per CEO directive ib-20260406-001
+try:
+    from llm_email_dedup import llm_dedup_check
+    _LLM_DEDUP_AVAILABLE = True
+except ImportError:
+    _LLM_DEDUP_AVAILABLE = False
+
+# Pre-draft context enrichment (Phase 7) — advisory, never blocks — fail-open
+try:
+    from pre_draft_lookup import pre_draft_lookup
+    _PRE_DRAFT_AVAILABLE = True
+except ImportError:
+    _PRE_DRAFT_AVAILABLE = False
+
+import json
+from pathlib import Path
+_AGENT_REPO_DIR = Path(os.environ.get("AGENT_DIR", str(Path(__file__).resolve().parent.parent)))
+try:
+    _AGENT = json.loads((_AGENT_REPO_DIR / "config" / "agent.json").read_text())
+except Exception:
+    _AGENT = {"firstName": "Agent", "fullName": "Agent", "email": "agent@example.com", "title": "Agent", "phone": ""}
+
+USER = _AGENT.get("email", "agent@example.com")
+LOGO_URL = os.environ.get(
+    "EMAIL_SIGNATURE_LOGO_URL",
+    "https://ci3.googleusercontent.com/mail-sig/AIorK4xNDnPN6a0MjSHV5urb9g11u2CzHIzwdJbwN21quGjzQFdbOdegCq1Wp6lq3NCqsARbi-ooqPfE9E1D",
+)
+
+
+def load_password():
+    """Load Gmail app password from environment or .env file."""
+    pw = os.environ.get("GMAIL_APP_PASSWORD", "")
+    if pw:
+        return pw
+    # Try loading from .env file
+    env_path = Path(__file__).parent.parent / ".env"
+    if env_path.exists():
+        with open(env_path) as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith("GMAIL_APP_PASSWORD="):
+                    return line.split("=", 1)[1].strip().strip('"').strip("'")
+    return ""
+
+
+PASSWORD = load_password()
+if not PASSWORD:
+    print("Error: GMAIL_APP_PASSWORD not set in environment or .env file.")
+    sys.exit(1)
+
+
+def get_thread_message_ids(subject_search):
+    """Fetch real Message-IDs from Gmail via IMAP for threading.
+
+    Searches BOTH Inbox and Sent Mail to find the full thread chain.
+    Gmail threads by In-Reply-To/References headers, so we need all
+    Message-IDs from the conversation regardless of folder.
+    """
+    try:
+        mail = imaplib.IMAP4_SSL("imap.gmail.com")
+        mail.login(USER, PASSWORD)
+
+        clean_subject = subject_search.replace("Re: ", "").replace("Fwd: ", "").strip()
+        msg_ids = []
+        seen = set()
+
+        # Search across both INBOX and Sent Mail
+        for folder in ["INBOX", "[Gmail]/Sent Mail"]:
+            try:
+                mail.select(folder)
+                status, messages = mail.search(None, f'(SUBJECT "{clean_subject}")')
+                if status == "OK" and messages[0]:
+                    for num in messages[0].split():
+                        status, data = mail.fetch(num, '(RFC822.HEADER)')
+                        if status == "OK":
+                            hdr = email.message_from_string(data[0][1].decode('utf-8', errors='replace'))
+                            mid = hdr.get('Message-ID', '')
+                            if mid and mid not in seen:
+                                msg_ids.append(mid)
+                                seen.add(mid)
+            except Exception:
+                continue
+
+        mail.logout()
+        return msg_ids
+    except Exception as e:
+        print(f"Warning: Could not fetch thread IDs: {e}")
+        return []
+
+
+def mark_as_read(sender):
+    """Mark emails from sender as read."""
+    try:
+        mail = imaplib.IMAP4_SSL("imap.gmail.com")
+        mail.login(USER, PASSWORD)
+        mail.select("INBOX")
+        status, messages = mail.search(None, f'(UNSEEN FROM "{sender}")')
+        if status == "OK" and messages[0]:
+            for num in messages[0].split():
+                mail.store(num, '+FLAGS', '\\Seen')
+        mail.logout()
+    except Exception as e:
+        print(f"Warning: Could not mark emails as read: {e}")
+
+
+def build_signature_html():
+    full_name = _AGENT.get("fullName", "Agent")
+    title = _AGENT.get("title", "")
+    phone = _AGENT.get("phone", "")
+    phone_line = f'<div style="font-size:x-small;color:#000;">{phone}</div>\n<div><br></div>\n' if phone else ""
+    address = os.environ.get(
+        "EMAIL_SIGNATURE_ADDRESS",
+        "Level 1, Innovation One, Dubai International Financial Centre, Dubai, UAE",
+    )
+    return f"""<div>
+<div style="font-size:small;"><b>{full_name}</b></div>
+<div style="font-size:small;">{title}</div>
+<div><br></div>
+<div><img src="{LOGO_URL}" width="125"></div>
+<div><br></div>
+{phone_line}<div style="font-size:x-small;color:#000;">{address}</div>
+<div style="font-size:x-small;color:#666;">_________________________________________</div>
+<div style="font-size:x-small;color:#999;">This email and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed. If you have received this email in error please notify the sender. This message contains confidential information and is intended only for the individual named. If you are not the named addressee you should not disseminate, distribute or copy this email. Please notify the sender immediately by email if you have received this email by mistake and delete this email from your system. If you are not the intended recipient you are notified that disclosing, copying, distributing, or taking any action in reliance on the contents of this information is strictly prohibited.</div>
+</div>"""
+
+
+def attach_file(msg, filepath):
+    """Attach a file to the email message."""
+    filepath = Path(filepath)
+    if not filepath.exists():
+        print(f"Error: Attachment file not found: {filepath}")
+        sys.exit(1)
+
+    filename = filepath.name
+    content_type, encoding = mimetypes.guess_type(str(filepath))
+
+    if content_type is None:
+        content_type = 'application/octet-stream'
+
+    maintype, subtype = content_type.split('/', 1)
+
+    with open(filepath, 'rb') as f:
+        file_data = f.read()
+
+    if maintype == 'image':
+        attachment = MIMEImage(file_data, _subtype=subtype)
+    elif maintype == 'application':
+        attachment = MIMEApplication(file_data, _subtype=subtype)
+    else:
+        attachment = MIMEBase(maintype, subtype)
+        attachment.set_payload(file_data)
+        encoders.encode_base64(attachment)
+
+    attachment.add_header('Content-Disposition', 'attachment', filename=filename)
+    msg.attach(attachment)
+    print(f"Attached: {filename} ({len(file_data):,} bytes, {content_type})")
+
+
+def check_already_sent(to, subject):
+    """Check Gmail Sent Mail for a recent email to the same recipient with same subject.
+    Returns True if a matching email was sent in the last 24 hours."""
+    try:
+        mail = imaplib.IMAP4_SSL("imap.gmail.com")
+        mail.login(USER, PASSWORD)
+        mail.select('"[Gmail]/Sent Mail"')
+        clean_subject = subject.replace("RE: ", "").replace("Re: ", "").strip()
+        from datetime import datetime, timedelta
+        since_date = (datetime.now() - timedelta(hours=24)).strftime("%d-%b-%Y")
+        status, messages = mail.search(None, f'(SINCE "{since_date}" TO "{to}" SUBJECT "{clean_subject}")')
+        found = status == "OK" and messages[0] and len(messages[0].split()) > 0
+        count = len(messages[0].split()) if found else 0
+        mail.logout()
+        if found:
+            print(f"SENT_MAIL_DEDUP: Found {count} matching email(s) to {to} with subject containing '{clean_subject}' in last 24h", file=sys.stderr)
+        return found
+    except Exception as e:
+        print(f"SENT_MAIL_CHECK_ERROR: {e}", file=sys.stderr)
+        return False  # fail-open
+
+
+def send_email(to, subject, body, cc=None, attachment=None, reply_subject=None, in_reply_to=None):
+    # ── Pre-draft context enrichment (Phase 7) ─────────────────────
+    # Look up recipient in entity index. Advisory only — never blocks sending.
+    # Logs context to logs/audit/{date}-pre-draft-lookups.jsonl
+    if _PRE_DRAFT_AVAILABLE:
+        try:
+            _ctx = pre_draft_lookup(to, message_type="email")
+            if _ctx and _ctx.get("communication", {}).get("standing_instructions"):
+                print(f"PRE_DRAFT: {len(_ctx['communication']['standing_instructions'])} standing instruction(s) for {to}", file=sys.stderr)
+        except Exception as e:
+            print(f"PRE_DRAFT_WARN (fail-open): {e}", file=sys.stderr)
+
+    # ── Layer 1: LLM-based dedup ──────────────────────────────────────
+    # Reads recent conversation history with the recipient, asks Claude Haiku
+    # whether this topic has already been addressed. Replaces the old
+    # subject+recipient lock per CEO directive ib-20260406-001.
+    if _LLM_DEDUP_AVAILABLE:
+        try:
+            llm_result = llm_dedup_check(to, subject, body)
+            if llm_result["skip"]:
+                print(f"DEDUP_SKIP (LLM): {llm_result['reason']} [confidence={llm_result['confidence']}, msgs_checked={llm_result['recent_messages']}]")
+                return
+            else:
+                print(f"LLM_DEDUP_OK: {llm_result['reason'][:100]} [msgs_checked={llm_result['recent_messages']}]", file=sys.stderr)
+        except Exception as e:
+            print(f"LLM_DEDUP_WARN (fail-open): {e}", file=sys.stderr)
+
+    # ── Layer 2: Gmail Sent folder check ─────────────────────────────
+    # Double-check against actual sent mail via IMAP
+    if check_already_sent(to, subject):
+        print(f"DEDUP_SKIP (sent mail check): Already sent to {to} with subject '{subject}' in last 24h")
+        return
+
+    # ── Layer 3: Content-hash dedup ──────────────────────────────────
+    # Outbound dedup: prevent concurrent sessions from sending the same email
+    _dedup_key = None
+    if _DEDUP_AVAILABLE:
+        try:
+            _dedup_key, _dedup_result = acquire_email_lock(to, subject, body)
+            if _dedup_result == "DEDUP_SKIP":
+                print("DEDUP_SKIP (content hash)")
+                return
+        except Exception:
+            pass  # fail-open
+
+    msg = MIMEMultipart('mixed')
+    msg['From'] = f"{_AGENT.get('fullName', 'Agent')} <{USER}>"
+    msg['To'] = to
+    msg['Subject'] = subject
+    msg['Date'] = formatdate(localtime=True)
+
+    if cc:
+        msg['Cc'] = cc
+
+    # Add threading headers if replying
+    # Priority: direct --in-reply-to > subject-based search
+    if in_reply_to:
+        msg['In-Reply-To'] = in_reply_to
+        msg['References'] = in_reply_to
+        # Also search for full chain to build References
+        if reply_subject:
+            thread_ids = get_thread_message_ids(reply_subject)
+            if thread_ids:
+                all_refs = thread_ids + [in_reply_to]
+                seen = []
+                for r in all_refs:
+                    if r not in seen:
+                        seen.append(r)
+                msg.replace_header('References', ' '.join(seen))
+    elif reply_subject:
+        thread_ids = get_thread_message_ids(reply_subject)
+        if thread_ids:
+            msg['In-Reply-To'] = thread_ids[-1]
+            msg['References'] = ' '.join(thread_ids)
+
+    # Build HTML body with signature
+    body_html = body.replace('\n', '<br>')
+    html = f"""<html><body style="font-family:Arial,Helvetica,sans-serif;font-size:small;color:#000;">
+<div>{body_html}</div>
+<br>
+{build_signature_html()}
+</body></html>"""
+
+    # Create the alternative part for HTML body
+    body_part = MIMEMultipart('alternative')
+    body_part.attach(MIMEText(html, 'html'))
+    msg.attach(body_part)
+
+    # Attach file if provided
+    if attachment:
+        attach_file(msg, attachment)
+
+    # Build recipient list for sending
+    recipients = [to]
+    if cc:
+        recipients.extend([addr.strip() for addr in cc.split(',')])
+
+    # Send
+    with smtplib.SMTP('smtp.gmail.com', 587) as server:
+        server.starttls()
+        server.login(USER, PASSWORD)
+        server.send_message(msg, to_addrs=recipients)
+
+    # Mark sender's emails as read
+    sender_domain = to.split('@')[-1] if '@' in to else ''
+    if sender_domain:
+        mark_as_read(to)
+
+    cc_note = f" (CC: {cc})" if cc else ""
+    attachment_note = f" [Attachment: {Path(attachment).name}]" if attachment else ""
+    print(f"Sent to {to}{cc_note}, subject: {subject}{attachment_note}")
+
+    # Post-send: confirm content-hash lock (audit trail)
+    if _DEDUP_AVAILABLE:
+        try:
+            confirm_email_lock(_dedup_key, f"To:{to} Subj:{subject}", to=to, subject=subject)
+        except Exception:
+            pass
+
+
+def parse_args():
+    """Parse command-line arguments."""
+    if len(sys.argv) < 4:
+        print("Usage: send-email-with-attachment.py <to> <subject> <body> [--cc email] [--attachment path] [--reply-to-subject 'subject']")
+        print()
+        print("Arguments:")
+        print("  to                    Recipient email address")
+        print("  subject               Email subject line")
+        print("  body                  Email body (plain text, newlines converted to <br>)")
+        print("  --cc                  CC email address(es), comma-separated")
+        print("  --attachment          Path to file to attach (PNG, PDF, etc.)")
+        print("  --reply-to-subject    Subject of original thread (for threading)")
+        sys.exit(1)
+
+    to = sys.argv[1]
+    subject = sys.argv[2]
+    body = sys.argv[3]
+    cc = None
+    attachment = None
+    reply_subject = None
+    in_reply_to = None
+
+    i = 4
+    while i < len(sys.argv):
+        if sys.argv[i] == '--cc' and i + 1 < len(sys.argv):
+            cc = sys.argv[i + 1]
+            i += 2
+        elif sys.argv[i] == '--attachment' and i + 1 < len(sys.argv):
+            attachment = sys.argv[i + 1]
+            i += 2
+        elif sys.argv[i] == '--reply-to-subject' and i + 1 < len(sys.argv):
+            reply_subject = sys.argv[i + 1]
+            i += 2
+        elif sys.argv[i] == '--in-reply-to' and i + 1 < len(sys.argv):
+            in_reply_to = sys.argv[i + 1]
+            i += 2
+        else:
+            print(f"Unknown argument: {sys.argv[i]}")
+            sys.exit(1)
+
+    return to, subject, body, cc, attachment, reply_subject, in_reply_to
+
+
+if __name__ == '__main__':
+    to, subject, body, cc, attachment, reply_subject, in_reply_to = parse_args()
+    send_email(to, subject, body, cc, attachment, reply_subject, in_reply_to)

package/scripts/send-email.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+# send-email.sh — Send HTML email via SMTP as the running agent
+# Usage: ./scripts/send-email.sh <to> <subject> <body> [cc] [in-reply-to] [references]
+set -e
+
+SCRIPT_DIR_INIT="$(cd "$(dirname "$0")" && pwd)"
+AGENT_REPO_DIR="${AGENT_DIR:-$(cd "$SCRIPT_DIR_INIT/.." && pwd)}"
+if [ -f "$AGENT_REPO_DIR/config/agent.env" ]; then
+  # shellcheck disable=SC1091
+  source "$AGENT_REPO_DIR/config/agent.env"
+fi
+
+TO="$1"
+SUBJECT="$2"
+BODY="$3"
+CC="$4"
+IN_REPLY_TO="$5"
+REFERENCES="$6"
+
+if [ -z "$TO" ] || [ -z "$SUBJECT" ] || [ -z "$BODY" ]; then
+  echo "Usage: send-email.sh <to> <subject> <body> [cc] [in-reply-to] [references]"
+  exit 1
+fi
+
+# --- Outbound dedup: content-hash only ---
+# Subject+recipient lock removed per CEO directive ib-20260406-001.
+# LLM-based dedup is now handled in the Python send scripts.
+# This shell script uses content-hash dedup only (catches identical body sends).
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DEDUP_ACQUIRED=""
+if [ -x "$SCRIPT_DIR/outbound-dedup.sh" ]; then
+  # Generate content-hash key and acquire lock
+  CONTENT_KEY=$("$SCRIPT_DIR/outbound-dedup.sh" generate-key email "$TO" "$SUBJECT" "$BODY" 2>/dev/null) || true
+  if [ -n "$CONTENT_KEY" ]; then
+    ACQUIRE_RESULT=$("$SCRIPT_DIR/outbound-dedup.sh" acquire email "$CONTENT_KEY" "${AGENT_SESSION_ID:-${SOPHIE_SESSION_ID:-${RAVI_SESSION_ID:-$$}}}" 2>/dev/null) || true
+    if [ "$ACQUIRE_RESULT" = "DEDUP_SKIP" ]; then
+      echo "DEDUP_SKIP"
+      exit 0
+    fi
+    if [ "$ACQUIRE_RESULT" = "CLAIMED" ]; then
+      DEDUP_ACQUIRED="1"
+    fi
+  fi
+  # If ERROR or empty, fall through (fail-open) — send anyway
+fi
+
+# Build headers
+HEADERS="To: ${TO}
+From: ${AGENT_FULL_NAME:-Agent} <${AGENT_EMAIL:-agent@example.com}>
+Subject: ${SUBJECT}
+MIME-Version: 1.0
+Content-Type: text/html; charset=UTF-8"
+
+if [ -n "$CC" ]; then
+  HEADERS="${HEADERS}
+Cc: ${CC}"
+fi
+
+if [ -n "$IN_REPLY_TO" ]; then
+  HEADERS="${HEADERS}
+In-Reply-To: <${IN_REPLY_TO}>"
+  if [ -n "$REFERENCES" ]; then
+    HEADERS="${HEADERS}
+References: ${REFERENCES}"
+  else
+    HEADERS="${HEADERS}
+References: <${IN_REPLY_TO}>"
+  fi
+fi
+
+LOGO_URL="${EMAIL_SIGNATURE_LOGO_URL:-https://ci3.googleusercontent.com/mail-sig/AIorK4xNDnPN6a0MjSHV5urb9g11u2CzHIzwdJbwN21quGjzQFdbOdegCq1Wp6lq3NCqsARbi-ooqPfE9E1D}"
+SIG_ADDRESS="${EMAIL_SIGNATURE_ADDRESS:-Level 1, Innovation One, Dubai International Financial Centre, Dubai, UAE}"
+SIG_PHONE_HTML=""
+if [ -n "${AGENT_PHONE:-}" ]; then
+  PHONE_TEL=$(echo "$AGENT_PHONE" | tr -d ' ')
+  SIG_PHONE_HTML="<div style=\"font-size:small;\"><a href=\"tel:${PHONE_TEL}\" style=\"color:#1155cc;\">${AGENT_PHONE}</a></div>
+<div><br></div>
+"
+fi
+
+# Build HTML body
+HTML_BODY="<html><body>
+<div style=\"font-family:Arial,Helvetica,sans-serif;font-size:small;color:#000;\">
+$(echo "$BODY" | sed 's/$/<br>/g')
+</div>
+<br>
+<div style=\"font-family:Arial,Helvetica,sans-serif;color:#000;\">
+<div style=\"font-size:small;\"><b>${AGENT_FULL_NAME:-Agent}</b></div>
+<div style=\"font-size:small;\">${AGENT_TITLE:-}</div>
+<div><br></div>
+<div><img src=\"${LOGO_URL}\" width=\"125\"></div>
+<div><br></div>
+${SIG_PHONE_HTML}<div style=\"font-size:x-small;color:#000;\">${SIG_ADDRESS}</div>
+<div style=\"font-size:x-small;color:#666;\">_________________________________________</div>
+<div><br></div>
+<div style=\"font-size:x-small;color:#999;\">This email and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed. If you have received this email in error please notify the sender. This message contains confidential information and is intended only for the individual named. If you are not the named addressee you should not disseminate, distribute or copy this email. Please notify the sender immediately by email if you have received this email by mistake and delete this email from your system. If you are not the intended recipient you are notified that disclosing, copying, distributing, or taking any action in reliance on the contents of this information is strictly prohibited.</div>
+</div>
+</body></html>"
+
+# ── Pre-send policy gate (shared send-gate chokepoint) ──────────────
+# Unified policy layer ABOVE the Python Layer-0 validator: banned phrases,
+# AI-disclosure, information barriers, recipient allowlist — all in
+# lib/comms/send-gate.mjs. Email recipients are external by default, so an
+# unreadable policy fails CLOSED here (mirrors validate_outbound semantics).
+SEND_GATE="$AGENT_REPO_DIR/lib/comms/send-gate.mjs"
+if [ ! -f "$SEND_GATE" ]; then
+  SEND_GATE="$AGENT_REPO_DIR/node_modules/@cohortapp/agent-sdk/lib/comms/send-gate.mjs"
+fi
+if [ -f "$SEND_GATE" ]; then
+  NODE_BIN="${MAESTRO_NODE_BIN:-/opt/homebrew/bin/node}"
+  command -v "$NODE_BIN" >/dev/null 2>&1 || NODE_BIN="node"
+  # Replies by default; MAESTRO_SEND_FIRST_CONTACT=true for first contact. The
+  # truthfulness invariant (never deny being an AI) applies regardless.
+  GATE_REASON=$(printf '%s' "$BODY" | AGENT_DIR="$AGENT_REPO_DIR" "$NODE_BIN" "$SEND_GATE" \
+    --channel email --recipient "$TO" --agent-root "$AGENT_REPO_DIR" \
+    --first-contact "${MAESTRO_SEND_FIRST_CONTACT:-false}" 2>&1) || GATE_EXIT=$?
+  GATE_EXIT=${GATE_EXIT:-0}
+  if [ "$GATE_EXIT" != "0" ]; then
+    echo "SEND_GATE_BLOCK: Email to $TO blocked by policy gate" >&2
+    echo "$GATE_REASON" >&2
+    exit 1
+  fi
+fi
+
+printf "%s\n\n%s" "$HEADERS" "$HTML_BODY" | msmtp -a northwind "$TO"
+
+# Post-send: confirm content-hash dedup lock
+if [ -n "$DEDUP_ACQUIRED" ] && [ -x "$SCRIPT_DIR/outbound-dedup.sh" ] && [ -n "$CONTENT_KEY" ]; then
+  PREVIEW=$(printf '%s' "$BODY" | head -c 200)
+  "$SCRIPT_DIR/outbound-dedup.sh" confirm email "$CONTENT_KEY" "To:$TO Subj:$SUBJECT $PREVIEW" 2>/dev/null || true
+fi

package/scripts/send-sms.sh

@@ -0,0 +1,175 @@
+#!/bin/bash
+# send-sms.sh — Send outbound SMS via Twilio REST API as the running agent
+# Usage: ./scripts/send-sms.sh --to "+1234567890" --body "message text"
+#
+# Environment variables (from .env):
+#   TWILIO_ACCOUNT_SID  — Twilio account SID
+#   TWILIO_AUTH_TOKEN   — Twilio auth token
+#   TWILIO_PHONE_NUMBER — The agent's Twilio phone number
+set -e
+
+# Load environment
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENT_REPO_DIR="${AGENT_DIR:-$(dirname "$SCRIPT_DIR")}"
+
+if [ -f "$AGENT_REPO_DIR/.env" ]; then
+  source "$AGENT_REPO_DIR/.env"
+fi
+
+# Defaults
+FROM_NUMBER="${TWILIO_PHONE_NUMBER:-+16282656712}"
+TO=""
+BODY=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --to)
+      TO="$2"
+      shift 2
+      ;;
+    --body)
+      BODY="$2"
+      shift 2
+      ;;
+    --from)
+      FROM_NUMBER="$2"
+      shift 2
+      ;;
+    -h|--help)
+      echo "Usage: send-sms.sh --to \"+1234567890\" --body \"message text\""
+      echo ""
+      echo "Options:"
+      echo "  --to     Recipient phone number (E.164 format, required)"
+      echo "  --body   Message text (required)"
+      echo "  --from   Sender phone number (default: \$TWILIO_PHONE_NUMBER or +16282656712)"
+      echo "  -h       Show this help"
+      exit 0
+      ;;
+    *)
+      echo "ERROR: Unknown argument: $1" >&2
+      echo "Usage: send-sms.sh --to \"+1234567890\" --body \"message text\"" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required arguments
+if [ -z "$TO" ]; then
+  echo "ERROR: --to is required" >&2
+  exit 1
+fi
+
+if [ -z "$BODY" ]; then
+  echo "ERROR: --body is required" >&2
+  exit 1
+fi
+
+# --- Outbound dedup: prevent concurrent sessions from sending the same SMS ---
+DEDUP_ACQUIRED=""
+if [ -x "$SCRIPT_DIR/outbound-dedup.sh" ]; then
+  DEDUP_KEY=$("$SCRIPT_DIR/outbound-dedup.sh" generate-key sms "$TO" "" "$BODY" 2>/dev/null) || true
+  if [ -n "$DEDUP_KEY" ]; then
+    ACQUIRE_RESULT=$("$SCRIPT_DIR/outbound-dedup.sh" acquire sms "$DEDUP_KEY" "${SOPHIE_SESSION_ID:-$$}" 2>/dev/null) || true
+    if [ "$ACQUIRE_RESULT" = "DEDUP_SKIP" ]; then
+      echo "DEDUP_SKIP: Another session is already sending this SMS"
+      exit 0
+    fi
+    if [ "$ACQUIRE_RESULT" = "CLAIMED" ]; then
+      DEDUP_ACQUIRED="1"
+    fi
+    # If ERROR or empty, fall through (fail-open) — send anyway
+  fi
+fi
+
+# Validate Twilio credentials
+if [ -z "$TWILIO_ACCOUNT_SID" ]; then
+  echo "ERROR: TWILIO_ACCOUNT_SID not set" >&2
+  exit 1
+fi
+
+if [ -z "$TWILIO_AUTH_TOKEN" ]; then
+  echo "ERROR: TWILIO_AUTH_TOKEN not set" >&2
+  exit 1
+fi
+
+# ── Pre-send policy gate (shared send-gate chokepoint) ──────────────
+# Unified policy layer: banned phrases, AI-disclosure, information barriers,
+# recipient allowlist — all in lib/comms/send-gate.mjs. SMS recipients are phone
+# numbers (external), so an unreadable policy fails CLOSED here.
+SEND_GATE="$AGENT_REPO_DIR/lib/comms/send-gate.mjs"
+if [ ! -f "$SEND_GATE" ]; then
+  SEND_GATE="$AGENT_REPO_DIR/node_modules/@cohortapp/agent-sdk/lib/comms/send-gate.mjs"
+fi
+if [ -f "$SEND_GATE" ]; then
+  NODE_BIN="${MAESTRO_NODE_BIN:-/opt/homebrew/bin/node}"
+  command -v "$NODE_BIN" >/dev/null 2>&1 || NODE_BIN="node"
+  # Replies by default; MAESTRO_SEND_FIRST_CONTACT=true for first contact. The
+  # truthfulness invariant (never deny being an AI) applies regardless.
+  GATE_REASON=$(printf '%s' "$BODY" | AGENT_DIR="$AGENT_REPO_DIR" "$NODE_BIN" "$SEND_GATE" \
+    --channel sms --recipient "$TO" --agent-root "$AGENT_REPO_DIR" \
+    --first-contact "${MAESTRO_SEND_FIRST_CONTACT:-false}" 2>&1) || GATE_EXIT=$?
+  GATE_EXIT=${GATE_EXIT:-0}
+  if [ "$GATE_EXIT" != "0" ]; then
+    echo "SEND_GATE_BLOCK: SMS to $TO blocked by policy gate" >&2
+    echo "$GATE_REASON" >&2
+    exit 1
+  fi
+fi
+
+# Send SMS via Twilio REST API
+RESPONSE=$(curl -s -w "\n%{http_code}" \
+  -X POST "https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}/Messages.json" \
+  -u "${TWILIO_ACCOUNT_SID}:${TWILIO_AUTH_TOKEN}" \
+  --data-urlencode "To=${TO}" \
+  --data-urlencode "From=${FROM_NUMBER}" \
+  --data-urlencode "Body=${BODY}")
+
+# Split response body and HTTP status code
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+RESPONSE_BODY=$(echo "$RESPONSE" | sed '$d')
+
+# Extract message SID from response
+MESSAGE_SID=$(echo "$RESPONSE_BODY" | grep -o '"sid": *"[^"]*"' | head -1 | sed 's/"sid": *"//' | sed 's/"//')
+STATUS=$(echo "$RESPONSE_BODY" | grep -o '"status": *"[^"]*"' | head -1 | sed 's/"status": *"//' | sed 's/"//')
+
+# Log to SMS log
+LOG_DIR="$AGENT_REPO_DIR/logs/sms/$(date +%Y-%m-%d)"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/$(date +%Y-%m-%d)-sms.jsonl"
+
+LOG_ENTRY=$(cat <<LOGEOF
+{"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)","direction":"outbound","messageSid":"${MESSAGE_SID}","from":"${FROM_NUMBER}","to":"${TO}","body":"$(echo "$BODY" | head -c 200 | sed 's/"/\\"/g' | tr '\n' ' ')","http_code":"${HTTP_CODE}","status":"${STATUS}","logged_at":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)"}
+LOGEOF
+)
+echo "$LOG_ENTRY" >> "$LOG_FILE"
+
+# Log to audit trail
+AUDIT_DIR="$AGENT_REPO_DIR/logs/audit"
+mkdir -p "$AUDIT_DIR"
+AUDIT_FILE="$AUDIT_DIR/$(date +%Y-%m-%d)-actions.jsonl"
+
+AUDIT_ENTRY=$(cat <<AUDITEOF
+{"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)","agent":"send-sms","action":"sms_sent","to":"${TO}","from":"${FROM_NUMBER}","body_preview":"$(echo "$BODY" | head -c 100 | sed 's/"/\\"/g' | tr '\n' ' ')","messageSid":"${MESSAGE_SID}","http_code":"${HTTP_CODE}","status":"${STATUS}"}
+AUDITEOF
+)
+echo "$AUDIT_ENTRY" >> "$AUDIT_FILE"
+
+# Output result
+if [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "200" ]; then
+  # Post-send: confirm the dedup lock (audit trail)
+  if [ -n "$DEDUP_ACQUIRED" ] && [ -n "$DEDUP_KEY" ] && [ -x "$SCRIPT_DIR/outbound-dedup.sh" ]; then
+    PREVIEW=$(printf '%s' "$BODY" | head -c 200)
+    "$SCRIPT_DIR/outbound-dedup.sh" confirm sms "$DEDUP_KEY" "To:$TO SID:$MESSAGE_SID $PREVIEW" 2>/dev/null || true
+  fi
+  echo "SMS sent successfully"
+  echo "  To: $TO"
+  echo "  From: $FROM_NUMBER"
+  echo "  SID: $MESSAGE_SID"
+  echo "  Status: $STATUS"
+  exit 0
+else
+  echo "ERROR: SMS send failed (HTTP $HTTP_CODE)" >&2
+  echo "$RESPONSE_BODY" >&2
+  exit 1
+fi