SMS Handler Pipeline

​

Pipeline Overview

1. Phone Resolution — Map phone number to family → member → role → access level
2. Context Loading — Load family.md, conversation history, member profile
3. Pre-Filter (Enforcement) — Strip restricted sections by access level
4. PHI Audit — Log context access with WHO/WHAT/WHEN/WHY
5. AI Generation — Call agent with filtered context
6. Post-Check (Enforcement) — Scan response for PHI leakage
7. Persistence — Apply family_file_updates (backup → edit → validate)
8. Logging — Record interaction in conversation timeline
9. Response Return — Return SMS text + metadata to caller

• Approval Gating — High-risk edits require YES/NO confirmation
• Outreach — Send messages to other team members
• Learning — Persist corrections to lessons.md
• Routing Updates — Add new family members

​

Entry Point

async def handle_sms(
    from_phone: str,
    body: str,
    dry_run: bool = False,
    service: str = "SMS"
) -> dict

​

Return Value

​

Key Functions

​

Phone Resolution

def resolve_phone(phone: str) -> dict | None

def resolve_chat_id(chat_id: str) -> dict | None

​

Context Loading

def load_family_context(family_dir: str) -> str

def load_recent_conversations(phone: str, limit: int = 50) -> str

​

System Prompt Assembly

def build_system_context(
    member: dict,
    family_context: str,
    conversation_history: str,
    service: str = "SMS",
    member_context: str = ""
) -> str

• SOUL.md (agent identity)
• agent_root.md (routing instructions)
• capabilities.md (CAN/CANNOT list)
• skills/*.md (conversation patterns)
• lessons.md (global + per-family corrections)
• Channel-specific guidance (iMessage vs SMS)
• Filtered family context
• Recent conversation history

​

AI Response Generation

async def generate_response(
    system_context: str,
    user_message: str,
    member_name: str = "there"
) -> str

• sms_response (text to send)
• internal_notes (agent reasoning)
• needs_outreach (array of outreach messages)
• family_file_updates (edits to apply)
• self_corrections (lessons to persist)
• member_updates (member profile edits)
• routing_updates (new member registrations)

​

Message Logging

def log_message(
    phone: str,
    direction: str,
    body: str,
    family_id: str = ""
)

1. /conversations/{phone}/{YYYY-MM}.log (per-member timeline)
2. /families/{family_id}/timeline/{YYYY-MM}.log (per-family timeline)

​

Response Schema

{
  "sms_response": "Message text to send (required)",
  "internal_notes": "Agent reasoning (required)",
  "needs_outreach": [
    {
      "phone": "+16514109390",
      "name": "Marcus",
      "message": "Liban is asking about tomorrow's schedule"
    }
  ],
  "family_file_updates": [
    {
      "section": "schedule",
      "operation": "append",
      "content": "- 2026-03-01 08:00: Doctor appointment (Marcus driving)",
      "old_content": ""
    }
  ],
  "self_corrections": [
    "[behavioral] Never use 'let me check' — always give the answer or say what's missing"
  ],
  "member_updates": [],
  "routing_updates": []
}

​

Access Levels

​

CLI Usage

# Dry run (test resolution without AI call)
python runtime/scripts/sms_handler.py \
  --from "+16517037981" \
  --body "Can someone take auntie to work tomorrow at 8am?" \
  --dry-run

# Full run (calls AI, applies updates)
python runtime/scripts/sms_handler.py \
  --from "+16517037981" \
  --body "Can someone take auntie to work tomorrow at 8am?"

​

Error Handling

​

Unknown Phone Number

• PHI audit logs the unknown number attempt
• Returns canned response: "Sorry, this number isn't set up to receive messages..."
• Zero PHI disclosed (hard rule)

​

AI Timeout/Failure

• Returns fallback message: "I hit a technical glitch processing your last message, {name}. Can you send it again?"
• Error logged to stderr
• No edits applied

​

Family Lock

​

Related

• Enforcement Layer — Role filter, PHI audit, approval gating
• Linq Integration — iMessage transport layer
• Configuration — Paths, API tokens, settings