@cohortapp/agent-sdk 2.3.0

package/scripts/sms-handler.mjs

@@ -0,0 +1,450 @@
+#!/usr/bin/env node
+/**
+ * Agent SMS Handler — Twilio Inbound SMS Webhook
+ *
+ * Receives inbound SMS/MMS via Twilio webhook, maps senders to known contacts,
+ * writes messages to the inbox for the inbox processor, and logs everything.
+ *
+ * Endpoints:
+ *   POST /sms       — Twilio SMS webhook (returns TwiML)
+ *   GET  /health    — Health check
+ *
+ * Environment:
+ *   TWILIO_ACCOUNT_SID   — For request validation (optional but recommended)
+ *   TWILIO_AUTH_TOKEN     — For request validation (optional but recommended)
+ *   SMS_PORT             — Port to listen on (default: 3001)
+ *
+ * Usage:
+ *   node scripts/sms-handler.mjs
+ *
+ * Configure in Twilio Console:
+ *   Phone Number → Messaging → "A message comes in" → Webhook → POST → <url>/sms
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import http from "node:http";
+import { URL } from "node:url";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const PORT = parseInt(process.env.SMS_PORT || "3001", 10);
+const AGENT_REPO_DIR =
+  process.env.AGENT_DIR ||
+  process.env.AGENT_REPO_DIR ||
+  path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+
+// Load identity from canonical SOT (config/agent.json).
+let _agent = null;
+function loadAgent() {
+  if (_agent) return _agent;
+  try {
+    _agent = JSON.parse(fs.readFileSync(path.join(AGENT_REPO_DIR, "config/agent.json"), "utf-8"));
+  } catch {
+    _agent = { firstName: "Agent", phone: "" };
+  }
+  return _agent;
+}
+
+const INBOX_DIR = path.join(AGENT_REPO_DIR, "state", "inbox", "sms");
+const LOG_DIR = path.join(AGENT_REPO_DIR, "logs", "sms");
+const CALLER_ID_MAP_PATH = path.join(AGENT_REPO_DIR, "config", "caller-id-map.yaml");
+const AGENT_NUMBER = loadAgent().phone || "";
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function ensureDir(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    // Already exists or inaccessible
+  }
+}
+
+function today() {
+  return new Date().toISOString().split("T")[0];
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * Load caller-id-map.yaml and build a phone-to-user lookup.
+ * Simple YAML parsing — avoids external dependency.
+ */
+function loadCallerIdMap() {
+  const map = new Map();
+  try {
+    const content = fs.readFileSync(CALLER_ID_MAP_PATH, "utf-8");
+    // Parse each user block: look for phone numbers and associated names
+    const userBlocks = content.split(/^\s{2}\w+:/gm);
+    const userKeys = content.match(/^\s{2}(\w+):/gm) || [];
+
+    for (let i = 0; i < userKeys.length; i++) {
+      const key = userKeys[i].trim().replace(":", "");
+      const block = userBlocks[i + 1] || "";
+
+      // Extract name
+      const nameMatch = block.match(/name:\s*"([^"]+)"/);
+      const name = nameMatch ? nameMatch[1] : key;
+
+      // Extract access level
+      const accessMatch = block.match(/access_level:\s*(\w+)/);
+      const accessLevel = accessMatch ? accessMatch[1] : "default";
+
+      // Extract email
+      const emailMatch = block.match(/email:\s*"([^"]+)"/);
+      const email = emailMatch ? emailMatch[1] : "";
+
+      // Extract phone numbers — handles both single and array format
+      const phoneMatch = block.match(/phone:\s*\[([^\]]*)\]/);
+      if (phoneMatch) {
+        const phones = phoneMatch[1].match(/"([^"]+)"/g) || [];
+        for (const phoneStr of phones) {
+          const phone = phoneStr.replace(/"/g, "");
+          map.set(phone, { id: key, name, accessLevel, email });
+        }
+      }
+    }
+  } catch (err) {
+    console.error(`[CALLER-MAP] Failed to load: ${err.message}`);
+  }
+  return map;
+}
+
+// Load on startup; reload periodically
+let callerMap = loadCallerIdMap();
+setInterval(() => {
+  callerMap = loadCallerIdMap();
+}, 60_000); // Reload every 60s
+
+/**
+ * Look up a phone number in the caller ID map.
+ */
+function lookupSender(phoneNumber) {
+  // Try exact match first
+  if (callerMap.has(phoneNumber)) {
+    return callerMap.get(phoneNumber);
+  }
+  // Try without + prefix
+  const stripped = phoneNumber.replace(/^\+/, "");
+  for (const [key, value] of callerMap) {
+    if (key.replace(/^\+/, "") === stripped) {
+      return value;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse URL-encoded form body (application/x-www-form-urlencoded).
+ */
+function parseFormBody(body) {
+  const params = new URLSearchParams(body);
+  const result = {};
+  for (const [key, value] of params) {
+    result[key] = value;
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+
+function logSms(entry) {
+  const dir = path.join(LOG_DIR, today());
+  ensureDir(dir);
+
+  const logFile = path.join(dir, `${today()}-sms.jsonl`);
+  const line = JSON.stringify({
+    ...entry,
+    logged_at: new Date().toISOString(),
+  });
+
+  try {
+    fs.appendFileSync(logFile, line + "\n");
+  } catch (err) {
+    console.error(`[LOG] Failed to write: ${err.message}`);
+  }
+
+  // Also log to stdout
+  console.log(
+    `[SMS] ${entry.direction || "inbound"} ${entry.from} -> ${entry.to}: ${(entry.body || "").substring(0, 100)}`,
+  );
+}
+
+/**
+ * Log to the agent's main audit trail (logs/audit/).
+ */
+function logAudit(action, details) {
+  const auditDir = path.join(AGENT_REPO_DIR, "logs", "audit");
+  ensureDir(auditDir);
+
+  const auditFile = path.join(auditDir, `${today()}-actions.jsonl`);
+  const entry = {
+    timestamp: new Date().toISOString(),
+    agent: "sms-handler",
+    action,
+    ...details,
+  };
+
+  try {
+    fs.appendFileSync(auditFile, JSON.stringify(entry) + "\n");
+  } catch (err) {
+    console.error(`[AUDIT] Failed to write: ${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Inbox Writer
+// ---------------------------------------------------------------------------
+
+/**
+ * Write an inbound SMS to the inbox as a YAML file for the inbox processor.
+ * Follows the same schema as Slack/Gmail inbox items.
+ */
+function writeToInbox(smsData) {
+  ensureDir(INBOX_DIR);
+
+  const ts = timestamp();
+  const filename = `${ts}-${smsData.MessageSid || "unknown"}.yaml`;
+  const filePath = path.join(INBOX_DIR, filename);
+
+  const sender = lookupSender(smsData.From || "");
+  const senderName = sender ? sender.name : smsData.From || "unknown";
+  const senderId = sender ? sender.id : "unknown";
+  const senderPrivilege = sender ? sender.accessLevel : "unknown";
+
+  // Check for media (MMS)
+  const numMedia = parseInt(smsData.NumMedia || "0", 10);
+  const mediaUrls = [];
+  for (let i = 0; i < numMedia; i++) {
+    const url = smsData[`MediaUrl${i}`];
+    const contentType = smsData[`MediaContentType${i}`];
+    if (url) {
+      mediaUrls.push({ url, content_type: contentType || "unknown" });
+    }
+  }
+
+  const yaml = [
+    `id: "${smsData.MessageSid || ts}"`,
+    `service: "sms"`,
+    `channel: "sms/${senderId}"`,
+    `sender: "${senderName}"`,
+    `sender_phone: "${smsData.From || ""}"`,
+    `sender_privilege: "${senderPrivilege}"`,
+    `timestamp: "${new Date().toISOString()}"`,
+    `subject: "SMS from ${senderName}"`,
+    `content: |`,
+    `  ${(smsData.Body || "").replace(/\n/g, "\n  ")}`,
+    `to: "${smsData.To || AGENT_NUMBER}"`,
+    `is_reply: false`,
+    `priority_signals:`,
+    `  from_ceo: ${senderPrivilege === "ceo"}`,
+    `  tagged_urgent: false`,
+    `  contains_deadline: false`,
+    `  mentions_agent: false`,
+  ];
+
+  if (mediaUrls.length > 0) {
+    yaml.push(`media:`);
+    for (const m of mediaUrls) {
+      yaml.push(`  - url: "${m.url}"`);
+      yaml.push(`    content_type: "${m.content_type}"`);
+    }
+  }
+
+  yaml.push(`raw_ref: "sms:${smsData.MessageSid || "unknown"}"`);
+
+  try {
+    fs.writeFileSync(filePath, yaml.join("\n") + "\n");
+    console.log(`[INBOX] Written: ${filename}`);
+    return filePath;
+  } catch (err) {
+    console.error(`[INBOX] Failed to write: ${err.message}`);
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// TwiML Response
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a minimal TwiML response.
+ * Empty <Response/> acknowledges receipt without sending a reply SMS.
+ */
+function twimlAck() {
+  return '<?xml version="1.0" encoding="UTF-8"?>\n<Response></Response>';
+}
+
+// ---------------------------------------------------------------------------
+// HTTP Server
+// ---------------------------------------------------------------------------
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+
+  // Health check
+  if (req.method === "GET" && url.pathname === "/health") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        status: "ok",
+        service: "agent-sms-handler",
+        uptime: process.uptime(),
+        timestamp: new Date().toISOString(),
+        knownContacts: callerMap.size,
+      }),
+    );
+    return;
+  }
+
+  // Root info
+  if (req.method === "GET" && url.pathname === "/") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(
+      JSON.stringify({
+        service: "Agent SMS Handler",
+        description: "Twilio inbound SMS webhook for the agent's inbox",
+        endpoints: {
+          health: "/health",
+          sms: "/sms (POST)",
+        },
+      }),
+    );
+    return;
+  }
+
+  // SMS webhook
+  if (req.method === "POST" && url.pathname === "/sms") {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      try {
+        const smsData = parseFormBody(body);
+
+        const from = smsData.From || "unknown";
+        const to = smsData.To || AGENT_NUMBER;
+        const messageBody = smsData.Body || "";
+        const messageSid = smsData.MessageSid || "unknown";
+        const numMedia = parseInt(smsData.NumMedia || "0", 10);
+
+        // Log the inbound SMS
+        logSms({
+          direction: "inbound",
+          messageSid,
+          from,
+          to,
+          body: messageBody,
+          numMedia,
+          timestamp: new Date().toISOString(),
+        });
+
+        // Write to inbox for processing
+        const inboxPath = writeToInbox(smsData);
+
+        // Log to audit trail
+        logAudit("sms_received", {
+          from,
+          to,
+          messageSid,
+          body_preview: messageBody.substring(0, 100),
+          inbox_path: inboxPath,
+          sender_identified: !!lookupSender(from),
+        });
+
+        // Check if from CEO — log as priority
+        const sender = lookupSender(from);
+        if (sender && sender.accessLevel === "ceo") {
+          console.log(
+            `[PRIORITY] SMS from CEO (${sender.name}): ${messageBody.substring(0, 100)}`,
+          );
+
+          // Write priority trigger
+          const priorityDir = path.join(
+            AGENT_REPO_DIR,
+            "state",
+            "inbox",
+            "processed",
+          );
+          ensureDir(priorityDir);
+          // Actually write to main inbox dir for the inbox processor to catch
+          const priorityFile = path.join(
+            INBOX_DIR,
+            `priority-${Date.now()}.yaml`,
+          );
+          const priorityYaml =
+            [
+              `type: priority_trigger`,
+              `reason: "SMS from CEO"`,
+              `source_item: "sms:${messageSid}"`,
+              `timestamp: "${new Date().toISOString()}"`,
+              `sender: "${sender.name}"`,
+              `channel: "sms/${sender.id}"`,
+              `content: |`,
+              `  ${messageBody.replace(/\n/g, "\n  ")}`,
+            ].join("\n") + "\n";
+
+          try {
+            fs.writeFileSync(priorityFile, priorityYaml);
+            console.log(`[PRIORITY] Priority trigger written`);
+          } catch (err) {
+            console.error(`[PRIORITY] Failed: ${err.message}`);
+          }
+        }
+
+        // Return TwiML acknowledgement (no auto-reply)
+        res.writeHead(200, { "Content-Type": "text/xml" });
+        res.end(twimlAck());
+      } catch (err) {
+        console.error(`[SMS] Error processing webhook: ${err.message}`);
+        // Still return valid TwiML to avoid Twilio retries
+        res.writeHead(200, { "Content-Type": "text/xml" });
+        res.end(twimlAck());
+      }
+    });
+    return;
+  }
+
+  // 404 for everything else
+  res.writeHead(404, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ error: "Not found" }));
+});
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+ensureDir(INBOX_DIR);
+ensureDir(LOG_DIR);
+
+server.listen(PORT, "0.0.0.0", () => {
+  console.log(`\n========================================`);
+  console.log(`  Agent SMS Handler`);
+  console.log(`  Port: ${PORT}`);
+  console.log(`  Health: http://0.0.0.0:${PORT}/health`);
+  console.log(`  Webhook: POST /sms`);
+  console.log(`  Known contacts: ${callerMap.size}`);
+  console.log(`  Inbox: ${INBOX_DIR}`);
+  console.log(`  Logs: ${LOG_DIR}`);
+  console.log(`========================================\n`);
+});
+
+// Graceful shutdown
+process.on("SIGTERM", () => {
+  console.log("[SMS] Shutting down...");
+  server.close(() => process.exit(0));
+});
+process.on("SIGINT", () => {
+  console.log("[SMS] Shutting down...");
+  server.close(() => process.exit(0));
+});

package/scripts/spawn-session.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# Spawn a dedicated Claude Code session for complex tasks
+# Usage: ./scripts/spawn-session.sh <session_id> <task_file> <time_budget_seconds>
+#
+# This script is called by the session-spawner agent when the inbound
+# dispatcher routes an item to spawn-session.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOPHIE_AI_DIR="$(dirname "$SCRIPT_DIR")"
+SESSION_ID="${1:?Session ID required}"
+TASK_FILE="${2:?Task file path required}"
+TIME_BUDGET="${3:-600}"  # Default 10 minutes
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+SESSION_DIR="$SOPHIE_AI_DIR/outputs/sessions/$SESSION_ID"
+LOG_FILE="$SOPHIE_AI_DIR/logs/sessions/$SESSION_ID.log"
+
+# Validate
+if [ -f "$SOPHIE_AI_DIR/.emergency-stop" ]; then
+    echo "[$TIMESTAMP] BLOCKED: Emergency stop is active" >&2
+    exit 1
+fi
+
+if [ ! -f "$TASK_FILE" ]; then
+    echo "[$TIMESTAMP] ERROR: Task file not found: $TASK_FILE" >&2
+    exit 1
+fi
+
+# --- Resource gate: refuse to spawn if machine is under pressure -------------
+MAX_CLAUDE_PROCS="${WATCHDOG_MAX_CLAUDE_PROCS:-8}"
+TOTAL_RAM_KB=$(sysctl -n hw.memsize | awk '{printf "%.0f", $1 / 1024}')
+SPAWN_BLOCK_PERCENT="${WATCHDOG_CRITICAL_PERCENT:-75}"
+
+claude_count=$(/bin/ps -eo comm | grep -ci "claude" | tr -d ' ' || true)
+claude_rss_kb=$(/bin/ps -eo rss,comm | grep -i "claude" | grep -v "Claude.app" | grep -v "Claude Helper" | awk '{sum+=$1} END {print sum+0}')
+claude_pct=$(( (claude_rss_kb * 100) / TOTAL_RAM_KB ))
+
+if [ "$claude_count" -ge "$MAX_CLAUDE_PROCS" ]; then
+    echo "[$TIMESTAMP] BLOCKED: Too many claude processes ($claude_count >= $MAX_CLAUDE_PROCS)" >&2
+    exit 1
+fi
+
+if [ "$claude_pct" -ge "$SPAWN_BLOCK_PERCENT" ]; then
+    echo "[$TIMESTAMP] BLOCKED: Claude memory usage ${claude_pct}% >= ${SPAWN_BLOCK_PERCENT}% threshold" >&2
+    exit 1
+fi
+# -----------------------------------------------------------------------------
+
+# Create session directory
+mkdir -p "$SESSION_DIR" "$(dirname "$LOG_FILE")"
+
+# Read the task
+TASK_CONTENT=$(cat "$TASK_FILE")
+
+# Write session manifest
+cat > "$SESSION_DIR/manifest.yaml" << YAML
+session_id: $SESSION_ID
+created: $TIMESTAMP
+task_file: $TASK_FILE
+time_budget_seconds: $TIME_BUDGET
+status: running
+pid: null
+YAML
+
+echo "[$TIMESTAMP] Spawning session $SESSION_ID (budget: ${TIME_BUDGET}s)" | tee -a "$LOG_FILE"
+
+# Spawn Claude Code session in background with timeout
+# Supports two backends:
+#   MAESTRO_SESSION_BACKEND=claude      (default) — direct claude -p
+#   MAESTRO_SESSION_BACKEND=claudraband — persistent sessions via claudraband daemon
+SESSION_BACKEND="${MAESTRO_SESSION_BACKEND:-claude}"
+
+SESSION_PROMPT="$TASK_CONTENT
+
+IMPORTANT: You are a sub-session spawned for a Northwind AI agent.
+Write your output to: $SESSION_DIR/output.md
+When complete, write 'DONE' to: $SESSION_DIR/complete
+Working directory: $SOPHIE_AI_DIR
+Do NOT send any communications. Only produce the requested output."
+
+(
+    if [ "$SESSION_BACKEND" = "claudraband" ]; then
+        # Use claudraband for persistent, resumable sessions
+        timeout "$TIME_BUDGET" npx @halfwhey/claudraband "$SESSION_PROMPT" \
+            --output-format text \
+            >> "$LOG_FILE" 2>&1
+    else
+        # Default: direct claude -p
+        timeout "$TIME_BUDGET" claude -p "$SESSION_PROMPT" \
+            --output-format text \
+            >> "$LOG_FILE" 2>&1
+    fi
+
+    EXIT_CODE=$?
+
+    if [ $EXIT_CODE -eq 0 ]; then
+        echo "DONE" > "$SESSION_DIR/complete"
+        # Update manifest
+        sed -i '' "s/status: running/status: completed/" "$SESSION_DIR/manifest.yaml"
+        echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] Session $SESSION_ID completed successfully" >> "$LOG_FILE"
+    elif [ $EXIT_CODE -eq 124 ]; then
+        echo "TIMEOUT" > "$SESSION_DIR/complete"
+        sed -i '' "s/status: running/status: timeout/" "$SESSION_DIR/manifest.yaml"
+        echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] Session $SESSION_ID TIMED OUT after ${TIME_BUDGET}s" >> "$LOG_FILE"
+    else
+        echo "ERROR:$EXIT_CODE" > "$SESSION_DIR/complete"
+        sed -i '' "s/status: running/status: error/" "$SESSION_DIR/manifest.yaml"
+        echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] Session $SESSION_ID failed with exit code $EXIT_CODE" >> "$LOG_FILE"
+    fi
+) &
+
+SESSION_PID=$!
+
+# Record PID in manifest
+sed -i '' "s/pid: null/pid: $SESSION_PID/" "$SESSION_DIR/manifest.yaml"
+
+echo "[$TIMESTAMP] Session $SESSION_ID spawned as PID $SESSION_PID" | tee -a "$LOG_FILE"
+echo "$SESSION_DIR"