@cohortapp/agent-sdk 2.3.0

package/scripts/whatsapp-handler.mjs

@@ -0,0 +1,538 @@
+#!/usr/bin/env node
+/**
+ * Agent WhatsApp Handler — Twilio Inbound WhatsApp Webhook
+ *
+ * Receives inbound WhatsApp messages via Twilio webhook, maps senders to known
+ * contacts, writes messages to the inbox for the inbox processor, and logs everything.
+ *
+ * WhatsApp messages arrive at Twilio via the same Messages webhook as SMS, but
+ * with "whatsapp:" prefix on the From/To fields. This handler listens on a
+ * separate port so it can be configured as the WhatsApp-specific webhook in Twilio.
+ *
+ * Endpoints:
+ *   POST /whatsapp      — Twilio WhatsApp webhook (returns TwiML)
+ *   POST /whatsapp/status — Delivery status callback
+ *   GET  /health         — Health check
+ *
+ * Environment:
+ *   TWILIO_ACCOUNT_SID   — For request validation
+ *   TWILIO_AUTH_TOKEN     — For request validation
+ *   WHATSAPP_PORT         — Port to listen on (default: 3002)
+ *
+ * Usage:
+ *   node scripts/whatsapp-handler.mjs
+ *
+ * Configure in Twilio Console:
+ *   WhatsApp Sandbox (or WABA) → "When a message comes in" → POST → <url>/whatsapp
+ *   Status callback → POST → <url>/whatsapp/status
+ */
+
+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.WHATSAPP_PORT || "3002", 10);
+const AGENT_REPO_DIR =
+  process.env.AGENT_DIR ||
+  process.env.AGENT_REPO_DIR ||
+  path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+
+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", "whatsapp");
+const LOG_DIR = path.join(AGENT_REPO_DIR, "logs", "whatsapp");
+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, "-");
+}
+
+/**
+ * Strip the "whatsapp:" prefix from phone numbers.
+ * Twilio sends WhatsApp numbers as "whatsapp:+1234567890".
+ */
+function stripWhatsAppPrefix(number) {
+  if (typeof number === "string" && number.startsWith("whatsapp:")) {
+    return number.substring(9);
+  }
+  return number || "";
+}
+
+/**
+ * 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");
+    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] || "";
+
+      const nameMatch = block.match(/name:\s*"([^"]+)"/);
+      const name = nameMatch ? nameMatch[1] : key;
+
+      const accessMatch = block.match(/access_level:\s*(\w+)/);
+      const accessLevel = accessMatch ? accessMatch[1] : "default";
+
+      const emailMatch = block.match(/email:\s*"([^"]+)"/);
+      const email = emailMatch ? emailMatch[1] : "";
+
+      // Extract phone numbers
+      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 });
+        }
+      }
+
+      // Also check for whatsapp-specific numbers
+      const waMatch = block.match(/whatsapp:\s*\[([^\]]*)\]/);
+      if (waMatch) {
+        const waNumbers = waMatch[1].match(/"([^"]+)"/g) || [];
+        for (const waStr of waNumbers) {
+          const waNum = waStr.replace(/"/g, "");
+          map.set(waNum, { 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);
+
+/**
+ * Look up a phone number in the caller ID map.
+ */
+function lookupSender(phoneNumber) {
+  const clean = stripWhatsAppPrefix(phoneNumber);
+  if (callerMap.has(clean)) {
+    return callerMap.get(clean);
+  }
+  const stripped = clean.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 logWhatsApp(entry) {
+  const dir = path.join(LOG_DIR, today());
+  ensureDir(dir);
+
+  const logFile = path.join(dir, `${today()}-whatsapp.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}`);
+  }
+
+  console.log(
+    `[WA] ${entry.direction || "inbound"} ${entry.from} -> ${entry.to}: ${(entry.body || "").substring(0, 100)}`,
+  );
+}
+
+/**
+ * Log to the main audit trail.
+ */
+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: "whatsapp-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 WhatsApp message to the inbox as a YAML file.
+ * Follows the same schema as SMS/Slack/Gmail inbox items.
+ */
+function writeToInbox(msgData) {
+  ensureDir(INBOX_DIR);
+
+  const ts = timestamp();
+  const messageSid = msgData.MessageSid || msgData.SmsSid || "unknown";
+  const filename = `${ts}-${messageSid}.yaml`;
+  const filePath = path.join(INBOX_DIR, filename);
+
+  const rawFrom = stripWhatsAppPrefix(msgData.From || "");
+  const sender = lookupSender(rawFrom);
+  const senderName = sender ? sender.name : rawFrom || "unknown";
+  const senderId = sender ? sender.id : "unknown";
+  const senderPrivilege = sender ? sender.accessLevel : "unknown";
+
+  // Check for media
+  const numMedia = parseInt(msgData.NumMedia || "0", 10);
+  const mediaUrls = [];
+  for (let i = 0; i < numMedia; i++) {
+    const url = msgData[`MediaUrl${i}`];
+    const contentType = msgData[`MediaContentType${i}`];
+    if (url) {
+      mediaUrls.push({ url, content_type: contentType || "unknown" });
+    }
+  }
+
+  // Detect message type hints
+  const body = msgData.Body || "";
+  const profileName = msgData.ProfileName || "";
+  const forwarded = msgData.Forwarded === "true";
+  const frequentlyForwarded = msgData.FrequentlyForwarded === "true";
+
+  const yaml = [
+    `id: "${messageSid}"`,
+    `service: "whatsapp"`,
+    `channel: "whatsapp/${senderId}"`,
+    `sender: "${senderName}"`,
+    `sender_phone: "${rawFrom}"`,
+    `sender_privilege: "${senderPrivilege}"`,
+    `sender_profile_name: "${profileName}"`,
+    `timestamp: "${new Date().toISOString()}"`,
+    `subject: "WhatsApp from ${senderName}"`,
+    `content: |`,
+    `  ${body.replace(/\n/g, "\n  ")}`,
+    `to: "${stripWhatsAppPrefix(msgData.To || "")}"`,
+    `is_reply: false`,
+    `is_forwarded: ${forwarded}`,
+    `is_frequently_forwarded: ${frequentlyForwarded}`,
+    `priority_signals:`,
+    `  from_ceo: ${senderPrivilege === "ceo"}`,
+    `  tagged_urgent: ${body.toLowerCase().includes("urgent")}`,
+    `  contains_deadline: false`,
+    `  mentions_agent: ${body.toLowerCase().includes((loadAgent().firstName || "agent").toLowerCase())}`,
+  ];
+
+  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: "whatsapp:${messageSid}"`);
+
+  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
+// ---------------------------------------------------------------------------
+
+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-whatsapp-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 WhatsApp Handler",
+        description: "Twilio inbound WhatsApp webhook for the agent's inbox",
+        endpoints: {
+          health: "/health",
+          whatsapp: "/whatsapp (POST)",
+          status: "/whatsapp/status (POST)",
+        },
+      }),
+    );
+    return;
+  }
+
+  // WhatsApp message webhook
+  if (req.method === "POST" && url.pathname === "/whatsapp") {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      try {
+        const msgData = parseFormBody(body);
+
+        const rawFrom = msgData.From || "unknown";
+        const rawTo = msgData.To || "";
+        const from = stripWhatsAppPrefix(rawFrom);
+        const to = stripWhatsAppPrefix(rawTo);
+        const messageBody = msgData.Body || "";
+        const messageSid = msgData.MessageSid || msgData.SmsSid || "unknown";
+        const numMedia = parseInt(msgData.NumMedia || "0", 10);
+        const profileName = msgData.ProfileName || "";
+
+        // Log the inbound WhatsApp message
+        logWhatsApp({
+          direction: "inbound",
+          messageSid,
+          from,
+          to,
+          body: messageBody,
+          numMedia,
+          profileName,
+          timestamp: new Date().toISOString(),
+        });
+
+        // Write to inbox for processing
+        const inboxPath = writeToInbox(msgData);
+
+        // Log to audit trail
+        logAudit("whatsapp_received", {
+          from,
+          to,
+          messageSid,
+          profileName,
+          body_preview: messageBody.substring(0, 100),
+          inbox_path: inboxPath,
+          sender_identified: !!lookupSender(from),
+          num_media: numMedia,
+        });
+
+        // Check if from CEO — log as priority
+        const sender = lookupSender(from);
+        if (sender && sender.accessLevel === "ceo") {
+          console.log(
+            `[PRIORITY] WhatsApp from CEO (${sender.name}): ${messageBody.substring(0, 100)}`,
+          );
+
+          // Write priority trigger
+          const priorityFile = path.join(
+            INBOX_DIR,
+            `priority-${Date.now()}.yaml`,
+          );
+          const priorityYaml =
+            [
+              `type: priority_trigger`,
+              `reason: "WhatsApp from CEO"`,
+              `source_item: "whatsapp:${messageSid}"`,
+              `timestamp: "${new Date().toISOString()}"`,
+              `sender: "${sender.name}"`,
+              `channel: "whatsapp/${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(`[WA] Error processing webhook: ${err.message}`);
+        res.writeHead(200, { "Content-Type": "text/xml" });
+        res.end(twimlAck());
+      }
+    });
+    return;
+  }
+
+  // Delivery status callback
+  if (req.method === "POST" && url.pathname === "/whatsapp/status") {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      try {
+        const statusData = parseFormBody(body);
+
+        const messageSid = statusData.MessageSid || "unknown";
+        const messageStatus = statusData.MessageStatus || "unknown";
+        const to = stripWhatsAppPrefix(statusData.To || "");
+        const from = stripWhatsAppPrefix(statusData.From || "");
+        const errorCode = statusData.ErrorCode || "";
+        const errorMessage = statusData.ErrorMessage || "";
+
+        logWhatsApp({
+          direction: "status",
+          messageSid,
+          from,
+          to,
+          status: messageStatus,
+          errorCode,
+          errorMessage,
+          timestamp: new Date().toISOString(),
+        });
+
+        // Log failures to audit
+        if (
+          messageStatus === "failed" ||
+          messageStatus === "undelivered" ||
+          errorCode
+        ) {
+          logAudit("whatsapp_delivery_failure", {
+            messageSid,
+            to,
+            from,
+            status: messageStatus,
+            errorCode,
+            errorMessage,
+          });
+          console.error(
+            `[WA-STATUS] DELIVERY FAILURE: ${messageSid} to ${to} — ${messageStatus} (${errorCode}: ${errorMessage})`,
+          );
+        } else {
+          console.log(
+            `[WA-STATUS] ${messageSid}: ${messageStatus}`,
+          );
+        }
+
+        res.writeHead(200, { "Content-Type": "text/xml" });
+        res.end(twimlAck());
+      } catch (err) {
+        console.error(`[WA-STATUS] Error: ${err.message}`);
+        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 WhatsApp Handler`);
+  console.log(`  Port: ${PORT}`);
+  console.log(`  Health: http://0.0.0.0:${PORT}/health`);
+  console.log(`  Webhook: POST /whatsapp`);
+  console.log(`  Status:  POST /whatsapp/status`);
+  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("[WA] Shutting down...");
+  server.close(() => process.exit(0));
+});
+process.on("SIGINT", () => {
+  console.log("[WA] Shutting down...");
+  server.close(() => process.exit(0));
+});

package/teams/desktop-operations.yaml

@@ -0,0 +1,34 @@
+# Desktop Operations Team
+# Controls real macOS applications on the Mac mini
+
+name: desktop-operations
+lead: desktop-operator
+description: >
+  Manages all desktop application control on the Mac mini.
+  The "hands" of the CEO Brain — executing Slack, email, WhatsApp,
+  and browser operations under strict governance.
+
+members:
+  - desktop-operator # Central desktop control coordinator
+  - slack-operator # Slack app control
+  - gmail-operator # Gmail browser control
+  - whatsapp-operator # WhatsApp Desktop control
+  - browser-operator # General browser operations
+  - calendar-ops # Calendar management (shared with executive-office)
+
+responsibilities:
+  - Application monitoring and observation
+  - Message drafting and sending (with approval)
+  - Channel and inbox triage
+  - Follow-up execution
+  - Screenshot capture and state verification
+  - Action logging and audit trail
+
+governance:
+  - All send operations require appropriate approval level
+  - All actions are logged with before/after state capture
+  - Rate limits enforced per application
+  - Emergency stop halts all desktop operations
+  - Forbidden actions are never executed regardless of instruction
+
+escalation: chief-of-staff

package/teams/executive-office.yaml

@@ -0,0 +1,27 @@
+# Executive Office Team
+# The core team that produces executive outputs and manages CEO operations
+
+name: executive-office
+lead: chief-of-staff
+description: >
+  The primary operating team. Produces all executive outputs, manages the
+  CEO's operational cadence, and coordinates across all domain teams.
+
+members:
+  - chief-of-staff # Team lead and orchestrator
+  - ceo-briefing # Brief and memo production
+  - communications # Outbound communications governance
+  - pmo-execution # Project tracking and follow-through
+  - calendar-ops # Calendar and scheduling
+  - decision-log # Decision recording
+  - workflow-automation # Scheduled workflow management
+
+responsibilities:
+  - Morning and evening briefs
+  - Communications triage and drafting
+  - Follow-up management
+  - Decision tracking
+  - Calendar management
+  - Executive cadence execution
+
+escalation: principal # Escalates to CEO

package/teams/legal-and-regulatory.yaml

@@ -0,0 +1,24 @@
+# Legal & Regulatory Team
+# Handles all legal, regulatory, and compliance matters
+
+name: legal-and-regulatory
+lead: regulatory-compliance
+description: >
+  Manages regulatory submission, legal structuring,
+  fund operations compliance, and risk management.
+
+members:
+  - regulatory-compliance # regulatory compliance
+  - legal-structuring # Legal entity and contract work
+  - fund-ops # Fund administration and investor reporting
+  - risk-register # Risk identification and tracking
+
+responsibilities:
+  - Regulatory gap remediation tracking
+  - Regulatory submission preparation
+  - Legal structuring for M&A
+  - Fund compliance and reporting
+  - Risk register maintenance
+  - Monthly risk refresh
+
+escalation: chief-of-staff

package/teams/platform-and-engineering.yaml

@@ -0,0 +1,23 @@
+# Platform & Engineering Team
+# Handles technical architecture, engineering coordination, and product strategy
+
+name: platform-and-engineering
+lead: product-strategy
+description: >
+  Manages the company's platform development, engineering coordination,
+  and technical architecture decisions.
+
+members:
+  - product-strategy # Product roadmap and prioritisation
+  - platform-architecture # Technical architecture
+  - engineering-coordination # Cross-repo engineering health
+
+responsibilities:
+  - Platform maturity tracking
+  - Engineering health monitoring
+  - Architecture decision support
+  - Technical debt management
+  - Build and test status
+  - Production readiness assessment
+
+escalation: chief-of-staff

package/teams/strategy-and-growth.yaml

@@ -0,0 +1,29 @@
+# Strategy & Growth Team
+# Handles strategic analysis, corporate development, and capital markets
+
+name: strategy-and-growth
+lead: strategic-planning
+description: >
+  Manages all strategic analysis, M&A execution, capital raising,
+  and competitive positioning for the company.
+
+members:
+  - strategic-planning # Strategic analysis and scenarios
+  - corporate-development # M&A and rollup execution
+  - rollup-target-sourcing # Acquisition target pipeline
+  - capital-raising # LP relationships and fundraising
+  - competitive-intelligence # Competitor monitoring
+  - market-research # Market and sector analysis
+  - partnerships # Strategic partnerships
+  - board-prep # Board materials and governance
+
+responsibilities:
+  - Weekly strategic memo
+  - Rollup pipeline management
+  - Deal preparation and execution
+  - Capital raising support
+  - Competitive intelligence
+  - Board pack preparation
+  - Quarterly scenario analysis
+
+escalation: chief-of-staff