@cohortapp/agent-sdk 2.3.0

package/scripts/setup/configure-twilio-sip-trunk.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * configure-twilio-sip-trunk.mjs — Provision a Twilio Elastic SIP Trunk
+ * that bridges PSTN voice traffic to OpenAI's native SIP connector,
+ * enabling live conversational outbound calls (placeOutboundCall) and
+ * inbound calls (when a phone rings → Twilio routes → OpenAI →
+ * realtime.call.incoming webhook fires on our voice-webhook-server).
+ *
+ * Usage:
+ *   node scripts/setup/configure-twilio-sip-trunk.mjs --openai-project=proj_xxxxxxxxxxxxxxxxx
+ *
+ * What it does:
+ *   1. Verifies TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN are set.
+ *   2. Creates a new Twilio Elastic SIP Trunk via POST /Trunks.
+ *   3. Sets the Origination URI to OpenAI's SIP endpoint:
+ *      sip:<project-id>@sip.api.openai.com;transport=tls
+ *   4. Writes TWILIO_SIP_TRUNK_SID + TWILIO_SIP_TRUNK_DOMAIN to .env.
+ *   5. Prints the OpenAI-dashboard steps the operator must complete to
+ *      whitelist the Twilio trunk on the OpenAI side.
+ *
+ * Idempotency: if a trunk with the same `friendly_name` already exists,
+ * we reuse it rather than creating a duplicate.
+ *
+ * Cost: Twilio Elastic SIP Trunking is metered (per-minute, varies by
+ * country). For US: ~$0.0085/min PSTN → SIP outbound.
+ *
+ * What this does NOT do (operator must complete in OpenAI dashboard):
+ *   - Whitelist Twilio's SIP origination URI in your OpenAI project's
+ *     SIP settings (platform.openai.com → project → Voice / SIP).
+ *   - Configure the inbound webhook URL (realtime.call.incoming) to
+ *     point at $VOICE_PUBLIC_BASE_URL/voice/sip/incoming.
+ */
+
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const args = Object.fromEntries(
+  process.argv.slice(2)
+    .map((a) => a.replace(/^--/, "").split("="))
+    .filter((p) => p.length === 2)
+);
+const projectId = args["openai-project"] || process.env.OPENAI_PROJECT_ID;
+const friendlyName = args["name"] || "maestro-openai-realtime";
+const dryRun = process.argv.includes("--dry-run");
+
+const ok = (m) => process.stdout.write(`[twilio-sip]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[twilio-sip]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[twilio-sip]  · ${m}\n`);
+
+// ── Validate inputs ────────────────────────────────────────────────────
+function loadEnv(p) {
+  if (!existsSync(p)) return;
+  for (const ln of readFileSync(p, "utf-8").split("\n")) {
+    const t = ln.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = t.indexOf("=");
+    if (eq <= 0) continue;
+    const k = t.slice(0, eq).trim();
+    let v = t.slice(eq + 1).trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+    if (!process.env[k]) process.env[k] = v;
+  }
+}
+loadEnv(join(AGENT_DIR, ".env"));
+
+const sid = process.env.TWILIO_ACCOUNT_SID;
+const token = process.env.TWILIO_AUTH_TOKEN;
+if (!sid || !token) {
+  warn("TWILIO_ACCOUNT_SID + TWILIO_AUTH_TOKEN required in .env");
+  process.exit(64);
+}
+if (!projectId) {
+  warn("Missing --openai-project=proj_xxxxxxxxxxxxxxxxx");
+  warn("Find it at: https://platform.openai.com/settings/organization/projects");
+  process.exit(64);
+}
+if (!/^proj_[A-Za-z0-9]{16,}$/.test(projectId)) {
+  warn(`OpenAI project id looks malformed: ${projectId}`);
+  warn("Expected format: proj_XXXXXXXXXXXXXXXX");
+  process.exit(64);
+}
+ok(`Twilio account: ${sid}`);
+ok(`OpenAI project: ${projectId}`);
+
+const sipUri = `sip:${projectId}@sip.api.openai.com;transport=tls`;
+ok(`SIP target: ${sipUri}`);
+
+if (dryRun) {
+  info("--dry-run set; not creating trunk.");
+  process.exit(0);
+}
+
+// ── Twilio API helper ──────────────────────────────────────────────────
+const TRUNK_API = "https://trunking.twilio.com/v1";
+const auth = "Basic " + Buffer.from(`${sid}:${token}`).toString("base64");
+
+async function twilio(path, init = {}) {
+  const r = await fetch(`${TRUNK_API}${path}`, {
+    ...init,
+    headers: {
+      Authorization: auth,
+      "Content-Type": "application/x-www-form-urlencoded",
+      ...(init.headers || {}),
+    },
+  });
+  const text = await r.text();
+  let data;
+  try { data = JSON.parse(text); } catch { data = { _raw: text }; }
+  if (!r.ok) {
+    throw new Error(`Twilio API ${path} → HTTP ${r.status}: ${data.message || text.slice(0, 300)}`);
+  }
+  return data;
+}
+
+// ── 1. Find or create the trunk ────────────────────────────────────────
+info("listing existing trunks for idempotency…");
+const list = await twilio(`/Trunks?PageSize=100`);
+let trunk = (list.trunks || []).find((t) => t.friendly_name === friendlyName);
+
+if (trunk) {
+  ok(`reusing existing trunk: ${trunk.sid} (${trunk.domain_name || "no domain set"})`);
+} else {
+  info(`creating new trunk "${friendlyName}"…`);
+  const params = new URLSearchParams({
+    FriendlyName: friendlyName,
+    CnamLookupEnabled: "false",
+    Transfer: "disable-all",
+  });
+  trunk = await twilio("/Trunks", { method: "POST", body: params.toString() });
+  ok(`created trunk: ${trunk.sid}`);
+}
+
+// Always ensure the trunk has a meaningful domain_name. Twilio creates
+// trunks with domain_name=null by default — only set explicitly via PUT.
+// Without this, our placeOutboundCall() dial-target gets "null.pstn.twilio.com".
+if (!trunk.domain_name) {
+  const safe = friendlyName.replace(/[^a-z0-9-]/gi, "-").toLowerCase().slice(0, 30);
+  const desired = `${safe}.pstn.twilio.com`;
+  info(`setting trunk domain_name=${desired}…`);
+  const params = new URLSearchParams({ DomainName: desired });
+  trunk = await twilio(`/Trunks/${trunk.sid}`, { method: "POST", body: params.toString() });
+  ok(`trunk domain set: ${trunk.domain_name}`);
+}
+
+// ── 2. Configure origination URL pointing at OpenAI SIP endpoint ───────
+info("configuring origination URL → OpenAI SIP endpoint…");
+const origList = await twilio(`/Trunks/${trunk.sid}/OriginationUrls?PageSize=10`);
+const desiredUri = sipUri;
+let originationUrl = (origList.origination_urls || []).find((u) => u.sip_url === desiredUri);
+
+if (originationUrl) {
+  ok(`origination URL already pointing at OpenAI (${originationUrl.sid})`);
+} else {
+  const params = new URLSearchParams({
+    FriendlyName: `openai-realtime-${projectId.slice(-8)}`,
+    SipUrl: desiredUri,
+    Weight: "1",
+    Priority: "1",
+    Enabled: "true",
+  });
+  originationUrl = await twilio(`/Trunks/${trunk.sid}/OriginationUrls`, {
+    method: "POST",
+    body: params.toString(),
+  });
+  ok(`created origination URL: ${originationUrl.sid}`);
+}
+
+// ── 3. Persist to .env ─────────────────────────────────────────────────
+const envPath = join(AGENT_DIR, ".env");
+let body = readFileSync(envPath, "utf-8");
+const updates = {
+  TWILIO_SIP_TRUNK_SID: trunk.sid,
+  TWILIO_SIP_TRUNK_DOMAIN: `${trunk.domain_name}.pstn.twilio.com`,
+  OPENAI_SIP_URI: sipUri,
+  OPENAI_PROJECT_ID: projectId,
+};
+for (const [k, v] of Object.entries(updates)) {
+  const re = new RegExp(`^${k}=.*$`, "m");
+  if (re.test(body)) body = body.replace(re, `${k}=${v}`);
+  else body += (body.endsWith("\n") ? "" : "\n") + `${k}=${v}\n`;
+}
+writeFileSync(envPath, body);
+ok("wrote TWILIO_SIP_TRUNK_SID / DOMAIN / OPENAI_SIP_URI / PROJECT_ID to .env");
+
+// ── 4. Print operator checklist for OpenAI side ────────────────────────
+console.log();
+info("=".repeat(60));
+info("OpenAI dashboard steps to complete:");
+info("=".repeat(60));
+info(`  1. Open https://platform.openai.com/settings/organization/projects/${projectId}`);
+info(`  2. Navigate to: Voice (or Real-time) → SIP settings`);
+info(`  3. Add the Twilio trunk's termination IPs to your allow-list.`);
+info(`     Twilio public IPs vary by region; see:`);
+info(`     https://www.twilio.com/docs/sip-trunking/ip-addresses`);
+info(`  4. Configure the inbound webhook ('realtime.call.incoming') to POST to:`);
+const publicBase = process.env.VOICE_PUBLIC_BASE_URL || "(set VOICE_PUBLIC_BASE_URL first)";
+info(`        ${publicBase}/voice/sip/incoming`);
+info(`  5. Save. OpenAI will fire that webhook on inbound calls; outbound`);
+info(`     calls via placeOutboundCall() will use the same SIP URI as the dial target.`);
+console.log();
+ok(`Trunk fully provisioned. Domain: ${trunk.domain_name}.pstn.twilio.com`);
+info("Test outbound: agent calls place_voice_call({ to: \"+447...\", brief: \"...\" })");

package/scripts/setup/configure-voice-tunnel.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * configure-voice-tunnel.mjs — Install + run a cloudflared tunnel that
+ * exposes the local voice-webhook-server (port 3200) on a public HTTPS
+ * URL so Twilio webhooks and OpenAI's SIP webhook can reach it.
+ *
+ * Two modes:
+ *   1. **ephemeral** (default, no args): uses cloudflared's
+ *      `trycloudflare.com` quick-tunnel feature — no account required,
+ *      no DNS to configure. URL changes whenever cloudflared restarts,
+ *      so this is only suitable for dev/testing.
+ *   2. **named**: `--named --domain voice.northwind.ai` — uses an
+ *      authenticated named tunnel routed to a custom hostname. Stable
+ *      URL across restarts. Requires `cloudflared tunnel login` to
+ *      have run + a domain on Cloudflare. Recommended for production.
+ *
+ * This script:
+ *   1. Verifies cloudflared is installed.
+ *   2. Generates the launchd plist from the template.
+ *   3. Loads the plist so launchd starts cloudflared.
+ *   4. Polls the cloudflared log for the public URL (ephemeral mode).
+ *   5. Writes VOICE_PUBLIC_BASE_URL to .env.
+ *   6. Restarts the voice-webhook-server so it picks up the new env var.
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+
+const args = new Set(process.argv.slice(2));
+const named = args.has("--named");
+const restart = !args.has("--no-restart");
+const domainArg = process.argv.find((a) => a.startsWith("--domain="));
+const domain = domainArg ? domainArg.split("=")[1] : null;
+
+const ok = (m) => process.stdout.write(`[voice-tunnel]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[voice-tunnel]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[voice-tunnel]  · ${m}\n`);
+
+if (named && !domain) {
+  warn("--named requires --domain=<hostname>");
+  process.exit(64);
+}
+
+// ── 1. cloudflared installed? ──────────────────────────────────────────
+const cfPath = ["/opt/homebrew/bin/cloudflared", "/usr/local/bin/cloudflared"]
+  .find((p) => existsSync(p));
+if (!cfPath) {
+  warn("cloudflared not installed. Install: brew install cloudflare/cloudflare/cloudflared");
+  process.exit(127);
+}
+ok(`cloudflared: ${cfPath}`);
+
+// Pull firstname for the launchd label so multi-agent hosts don't collide.
+let firstname = "agent";
+try {
+  const aj = JSON.parse(readFileSync(join(AGENT_DIR, "config/agent.json"), "utf-8"));
+  firstname = (aj.firstName || "agent").toLowerCase();
+} catch { /* fall through */ }
+
+const label = `ai.maestro.${firstname}-voice-tunnel`;
+const plistInstalled = join(process.env.HOME || "/", "Library/LaunchAgents", `${label}.plist`);
+
+// ── 2. Generate plist from template ────────────────────────────────────
+const templatePath = join(MAESTRO_ROOT, "scripts/local-triggers/templates/voice-tunnel.plist.template");
+if (!existsSync(templatePath)) {
+  warn(`template missing at ${templatePath}`);
+  process.exit(1);
+}
+let template = readFileSync(templatePath, "utf-8");
+const nodeBin = process.execPath; // not used here, but kept for consistency
+const substitutions = {
+  "{{FIRSTNAME}}": firstname,
+  "{{AGENT_ROOT}}": AGENT_DIR,
+  "{{HOME}}": process.env.HOME || `/Users/${firstname}`,
+  "{{USER}}": process.env.USER || firstname,
+};
+for (const [k, v] of Object.entries(substitutions)) {
+  template = template.split(k).join(v);
+}
+
+// In named mode we override ProgramArguments to use `cloudflared tunnel
+// run` with the named-tunnel UUID. For now the ephemeral path is the
+// default; named requires the operator to set up the tunnel & DNS first.
+if (named) {
+  template = template.replace(
+    /<array>[\s\S]*?<\/array>/,
+    `<array>
+        <string>${cfPath}</string>
+        <string>tunnel</string>
+        <string>run</string>
+        <string>--hostname</string>
+        <string>${domain}</string>
+        <string>${firstname}-voice</string>
+    </array>`
+  );
+}
+
+mkdirSync(dirname(plistInstalled), { recursive: true });
+mkdirSync(join(AGENT_DIR, "logs/voice"), { recursive: true });
+writeFileSync(plistInstalled, template);
+ok(`wrote ${plistInstalled}`);
+
+// ── 3. Load via launchctl ──────────────────────────────────────────────
+try { execFileSync("launchctl", ["unload", plistInstalled], { stdio: "pipe" }); } catch { /* */ }
+execFileSync("launchctl", ["load", plistInstalled], { stdio: "inherit" });
+ok(`loaded ${label}`);
+
+// ── 4. Wait for public URL ──────────────────────────────────────────────
+const stdoutLog = join(AGENT_DIR, "logs/voice/cloudflared-stdout.log");
+const stderrLog = join(AGENT_DIR, "logs/voice/cloudflared-stderr.log");
+
+let publicUrl = null;
+if (named) {
+  publicUrl = `https://${domain}`;
+  info(`named tunnel — public URL: ${publicUrl}`);
+} else {
+  info("polling cloudflared log for ephemeral URL (up to 30s)...");
+  for (let i = 0; i < 60 && !publicUrl; i++) {
+    await new Promise((r) => setTimeout(r, 500));
+    for (const path of [stdoutLog, stderrLog]) {
+      if (!existsSync(path)) continue;
+      const body = readFileSync(path, "utf-8");
+      const m = body.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/);
+      if (m) { publicUrl = m[0]; break; }
+    }
+  }
+  if (!publicUrl) {
+    warn("ephemeral URL not detected after 30s; check logs/voice/cloudflared-stderr.log");
+    process.exit(1);
+  }
+  ok(`ephemeral URL: ${publicUrl}`);
+}
+
+// ── 5. Update .env ──────────────────────────────────────────────────────
+const envPath = join(AGENT_DIR, ".env");
+if (!existsSync(envPath)) {
+  warn(".env not found — cannot persist VOICE_PUBLIC_BASE_URL");
+} else {
+  let body = readFileSync(envPath, "utf-8");
+  if (/^VOICE_PUBLIC_BASE_URL=/m.test(body)) {
+    body = body.replace(/^VOICE_PUBLIC_BASE_URL=.*$/m, `VOICE_PUBLIC_BASE_URL=${publicUrl}`);
+  } else {
+    if (!body.endsWith("\n")) body += "\n";
+    body += `\n# Public base URL for voice webhooks (set by configure-voice-tunnel.mjs)\nVOICE_PUBLIC_BASE_URL=${publicUrl}\n`;
+  }
+  writeFileSync(envPath, body);
+  ok("wrote VOICE_PUBLIC_BASE_URL to .env");
+}
+
+// ── 6. Restart voice-webhook so it picks up the env change ─────────────
+if (restart) {
+  const webhookLabel = `ai.maestro.${firstname}-voice-webhook`;
+  const webhookPlist = join(process.env.HOME || "/", "Library/LaunchAgents", `${webhookLabel}.plist`);
+  if (existsSync(webhookPlist)) {
+    try { execFileSync("launchctl", ["unload", webhookPlist], { stdio: "pipe" }); } catch { /* */ }
+    execFileSync("launchctl", ["load", webhookPlist], { stdio: "inherit" });
+    ok(`restarted ${webhookLabel}`);
+  } else {
+    info(`voice-webhook plist not installed (${webhookPlist}); run init-voice-realtime first`);
+  }
+}
+
+console.log();
+ok("done");
+info("Verify it works:");
+info(`  curl -s ${publicUrl}/health | jq`);
+info(`  open ${publicUrl}/voice/test`);
+console.log();
+if (!named) {
+  warn("This is an EPHEMERAL URL — it changes on every cloudflared restart.");
+  warn("For production, set up a named tunnel:");
+  warn("  cloudflared tunnel login           # auth Cloudflare account");
+  warn("  cloudflared tunnel create <name>   # creates UUID + creds");
+  warn("  cloudflared tunnel route dns <name> voice.your-domain.com");
+  warn("  node scripts/setup/configure-voice-tunnel.mjs --named --domain=voice.your-domain.com");
+}

package/scripts/setup/generate-agent-env.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * generate-agent-env.mjs — Generate config/agent.env from config/agent.json
+ *
+ * Shell scripts can't import TypeScript or parse JSON cheaply, so we
+ * pre-derive a flat env file that any bash script can source:
+ *
+ *   source "$AGENT_DIR/config/agent.env"
+ *   echo "Hello, $AGENT_FIRST_NAME"
+ *
+ * The generator is invoked:
+ *   - During `npm run init-agent` (initial setup)
+ *   - At the end of every `maestro upgrade` run
+ *   - On demand: `node scripts/setup/generate-agent-env.mjs`
+ *
+ * No TypeScript runtime required — we read agent.json directly.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_DIR || resolve(__dirname, "../..");
+const JSON_PATH = resolve(AGENT_DIR, "config/agent.json");
+const ENV_PATH = resolve(AGENT_DIR, "config/agent.env");
+
+if (!existsSync(JSON_PATH)) {
+  console.error(`[generate-agent-env] config/agent.json not found at ${JSON_PATH}`);
+  console.error("[generate-agent-env] Run /init-maestro to configure identity, or migrate from config/agent.ts");
+  process.exit(1);
+}
+
+const agent = JSON.parse(readFileSync(JSON_PATH, "utf-8"));
+
+// Shell-quote: wrap in single quotes; replace ' with '\'' (close, escape, reopen).
+const q = (v) => {
+  const s = v === null || v === undefined ? "" : String(v);
+  return `'${s.replace(/'/g, "'\\''")}'`;
+};
+
+const repoDir = `$HOME/${agent.repoSlug}`;
+const firstUpper = (agent.firstName || "").toUpperCase();
+const firstLower = (agent.firstName || "").toLowerCase();
+const signature = `${agent.fullName} | ${agent.title} | ${agent.company}`;
+
+const lines = [
+  `# Auto-generated from config/agent.json by @cohortapp/agent-sdk.`,
+  `# DO NOT EDIT — regenerate with: node scripts/setup/generate-agent-env.mjs`,
+  `# Sourced by every shell script that needs agent identity.`,
+  ``,
+  `# ── Agent identity ─────────────────────────────────────────────────`,
+  `export AGENT_FIRST_NAME=${q(agent.firstName)}`,
+  `export AGENT_LAST_NAME=${q(agent.lastName)}`,
+  `export AGENT_FULL_NAME=${q(agent.fullName)}`,
+  `export AGENT_TITLE=${q(agent.title)}`,
+  `export AGENT_ARCHETYPE=${q(agent.archetype)}`,
+  `export AGENT_EMAIL=${q(agent.email)}`,
+  `export AGENT_PHONE=${q(agent.phone)}`,
+  `export AGENT_SLACK_USER_ID=${q(agent.slackMemberId)}`,
+  `export AGENT_REPO_SLUG=${q(agent.repoSlug)}`,
+  `export AGENT_REPO_DIR="${repoDir}"`,
+  `export AGENT_MACHINE_NAME=${q(agent.machineName)}`,
+  `export AGENT_LAUNCHD_PREFIX=${q(agent.launchdLabelPrefix)}`,
+  `export AGENT_TIMEZONE=${q(agent.timezone)}`,
+  `export AGENT_LOCALE=${q(agent.locale)}`,
+  `export AGENT_UPPER=${q(firstUpper)}`,
+  `export AGENT_LOWER=${q(firstLower)}`,
+  `export AGENT_EMAIL_SIGNATURE=${q(signature)}`,
+  ``,
+  `# ── Principal ──────────────────────────────────────────────────────`,
+  `export PRINCIPAL_FIRST_NAME=${q(agent.principal?.firstName)}`,
+  `export PRINCIPAL_LAST_NAME=${q(agent.principal?.lastName)}`,
+  `export PRINCIPAL_FULL_NAME=${q(agent.principal?.fullName)}`,
+  `export PRINCIPAL_TITLE=${q(agent.principal?.title)}`,
+  `export PRINCIPAL_EMAIL=${q(agent.principal?.email)}`,
+  `export PRINCIPAL_SLACK_USER_ID=${q(agent.principal?.slackMemberId)}`,
+  ``,
+  `# ── Company ────────────────────────────────────────────────────────`,
+  `export COMPANY_NAME=${q(agent.company)}`,
+  `export COMPANY_DOMAIN=${q(agent.companyDomain)}`,
+  `export COMPANY_DESCRIPTION=${q(agent.companyDescription)}`,
+  ``,
+  `# ── Schedule ───────────────────────────────────────────────────────`,
+  `export SCHEDULE_MORNING_BRIEF=${q(agent.schedule?.morningBrief)}`,
+  `export SCHEDULE_EVENING_WRAP=${q(agent.schedule?.eveningWrap)}`,
+  `export SCHEDULE_OVERNIGHT_MONITORING=${q(agent.schedule?.overnightMonitoring)}`,
+  ``,
+];
+
+writeFileSync(ENV_PATH, lines.join("\n"));
+console.log(`[generate-agent-env] wrote ${ENV_PATH}`);