@cohortapp/agent-sdk 2.3.0

package/scripts/poller/lib/cloud-relay-dedup.test.mjs

@@ -0,0 +1,133 @@
+/**
+ * cloud-relay-dedup.test.mjs — node:test coverage for the pure SSE-parsing and
+ * reconnect-replay dedup helpers used by the Slack cloud-relay client
+ * (audit L30).
+ *
+ * These functions are pure (no network, no disk, no dotenv), so we import them
+ * directly from the extracted module — importing the client itself would pull
+ * in dotenv and open a live SSE connection.
+ *
+ * The reconnect-replay dedup (isReplayInSiblings) pins a production regression
+ * fixed in commit ccfbaed, where the same event was re-delivered after each
+ * relay reconnect; the `.processed` cases below guard that specifically.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  createSseParser,
+  isReplayInSiblings,
+} from "./cloud-relay-dedup.mjs";
+
+// ---------------------------------------------------------------------------
+// createSseParser — SSE framing
+// ---------------------------------------------------------------------------
+
+test("createSseParser emits one payload per blank-line-terminated event", () => {
+  const parser = createSseParser();
+  const out = parser.push('data: {"a":1}\n\n');
+  assert.deepEqual(out, ['{"a":1}']);
+});
+
+test("createSseParser buffers an event until its terminating blank line", () => {
+  const parser = createSseParser();
+  // No blank line yet — nothing should be emitted.
+  assert.deepEqual(parser.push('data: {"a":1}\n'), []);
+  // Blank line arrives in a later chunk — now it flushes.
+  assert.deepEqual(parser.push("\n"), ['{"a":1}']);
+});
+
+test("createSseParser concatenates multi-line data: with newlines", () => {
+  const parser = createSseParser();
+  const out = parser.push("data: line1\ndata: line2\n\n");
+  assert.deepEqual(out, ["line1\nline2"]);
+});
+
+test("createSseParser ignores ':' comment heartbeat lines", () => {
+  const parser = createSseParser();
+  // ": hb" is a heartbeat comment and must not produce or pollute a payload.
+  const out = parser.push(': hb\ndata: {"x":true}\n\n');
+  assert.deepEqual(out, ['{"x":true}']);
+});
+
+test("createSseParser strips exactly one leading space after 'data:'", () => {
+  const parser = createSseParser();
+  // Per the SSE spec, a single leading space after the colon is removed; a
+  // second space is significant payload content.
+  const out = parser.push("data:  two-spaces\n\n");
+  assert.deepEqual(out, [" two-spaces"]);
+});
+
+test("createSseParser tolerates CRLF line endings", () => {
+  const parser = createSseParser();
+  const out = parser.push('data: {"crlf":1}\r\n\r\n');
+  assert.deepEqual(out, ['{"crlf":1}']);
+});
+
+test("createSseParser handles two events split across chunk boundaries", () => {
+  const parser = createSseParser();
+  let out = parser.push('data: {"n":1}\n\nda');
+  assert.deepEqual(out, ['{"n":1}']);
+  out = parser.push('ta: {"n":2}\n\n');
+  assert.deepEqual(out, ['{"n":2}']);
+});
+
+test("createSseParser emits nothing for a comment-only / empty flush", () => {
+  const parser = createSseParser();
+  // A blank line with no preceding data: lines must not emit an empty payload.
+  assert.deepEqual(parser.push("\n"), []);
+  assert.deepEqual(parser.push(": keepalive\n\n"), []);
+});
+
+// ---------------------------------------------------------------------------
+// isReplayInSiblings — filesystem reconnect-replay dedup
+// ---------------------------------------------------------------------------
+
+const TS_KEY = "1700000000-001000"; // Slack ts "1700000000.001000" with dot→dash
+
+test("isReplayInSiblings is false when no sibling matches", () => {
+  const siblings = [
+    "2026-05-31T00-00-00-000Z-9999999999-000000-cloud-relay.json",
+    "unrelated.json",
+  ];
+  assert.equal(isReplayInSiblings(siblings, TS_KEY), false);
+});
+
+test("isReplayInSiblings detects a pending sibling for the same ts", () => {
+  const siblings = [
+    `2026-05-31T00-00-00-000Z-${TS_KEY}-cloud-relay.json`,
+  ];
+  assert.equal(isReplayInSiblings(siblings, TS_KEY), true);
+});
+
+test("isReplayInSiblings detects an already-processed sibling for the same ts", () => {
+  // The reconnect-replay regression (ccfbaed): a .processed file for the same
+  // ts must still count as a replay so we don't re-deliver after the daemon
+  // consumed it.
+  const siblings = [
+    `2026-05-31T00-00-00-000Z-${TS_KEY}-cloud-relay.json.processed`,
+  ];
+  assert.equal(isReplayInSiblings(siblings, TS_KEY), true);
+});
+
+test("isReplayInSiblings is false for a different ts key", () => {
+  const siblings = [
+    "2026-05-31T00-00-00-000Z-1700000000-999999-cloud-relay.json",
+    "2026-05-31T00-00-00-000Z-1700000000-999999-cloud-relay.json.processed",
+  ];
+  assert.equal(isReplayInSiblings(siblings, TS_KEY), false);
+});
+
+test("isReplayInSiblings is false on an empty inbox", () => {
+  assert.equal(isReplayInSiblings([], TS_KEY), false);
+});
+
+test("isReplayInSiblings does not false-match a ts that is a prefix of another", () => {
+  // Guard the suffix match: a longer ts key whose filename merely contains
+  // TS_KEY before extra digits must not be treated as a replay.
+  const siblings = [
+    `2026-05-31T00-00-00-000Z-${TS_KEY}9-cloud-relay.json`,
+  ];
+  assert.equal(isReplayInSiblings(siblings, TS_KEY), false);
+});

package/scripts/poller/lib/slash-command-handlers.mjs

@@ -0,0 +1,177 @@
+/**
+ * Maestro — Slash command handlers (Slack Socket Mode)
+ *
+ * Slack huddles use proprietary WebRTC with no programmatic-join API. The
+ * pragmatic equivalent is a slash command that hands the agent a "please call
+ * me" trigger, and the agent dials back via the same OpenAI Realtime + Twilio
+ * stack that powers PSTN calls. Same identity, same context-loader, same tool
+ * surface — just initiated from Slack instead of dialed in by phone.
+ *
+ * Currently supported commands:
+ *   /voice                 — call user's phone (looked up from config/contacts.yaml by slack_id)
+ *   /voice +44XXXX         — call this specific E.164 number
+ *   /voice "brief text"    — call user, with the given brief as the call objective
+ *   /voice +44XXX "brief"  — both
+ *
+ * Returns: { success, message, action_taken } — the message lands in Slack via
+ * the slash-command response_url (ephemeral by default, only the invoker sees it).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Look up a Slack user's phone number from config/contacts.yaml. Falls back to
+ * an explicit override in env (PHONE_BY_SLACK_ID_<slackid>) so operators can
+ * supply numbers without committing them to the contacts file. Returns null if
+ * no phone is found.
+ */
+async function resolvePhoneForSlackUser(agentRoot, slackUserId) {
+  if (!slackUserId) return null;
+
+  // Env override: PHONE_BY_SLACK_ID_U099XXXX=+44XXX
+  const envKey = `PHONE_BY_SLACK_ID_${slackUserId}`;
+  if (process.env[envKey]) return process.env[envKey];
+
+  const contactsPath = join(agentRoot, "config/contacts.yaml");
+  if (!existsSync(contactsPath)) return null;
+  let parsed;
+  try {
+    const yaml = await import("js-yaml");
+    parsed = yaml.load(readFileSync(contactsPath, "utf-8"));
+  } catch { return null; }
+  const list = parsed?.contacts || [];
+  for (const c of list) {
+    if (c?.slack_id === slackUserId) {
+      // Phone may live in a few field names depending on contacts.yaml shape
+      return c.phone || c.phone_e164 || c.mobile || c.cell || null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse `/voice` arguments. Format: optional `+E164` followed by optional
+ * quoted brief, e.g.
+ *   /voice                       → {phone: null, brief: null}
+ *   /voice +14155551212           → {phone: "+14155551212", brief: null}
+ *   /voice quick scheduling chat  → {phone: null, brief: "quick scheduling chat"}
+ *   /voice +14155551212 status    → {phone: "+14155551212", brief: "status"}
+ */
+export function parseVoiceArgs(text) {
+  const trimmed = String(text || "").trim();
+  if (!trimmed) return { phone: null, brief: null };
+  const phoneMatch = trimmed.match(/^(\+\d{6,16})\s*(.*)$/);
+  if (phoneMatch) {
+    return {
+      phone: phoneMatch[1],
+      brief: phoneMatch[2] ? phoneMatch[2].trim() : null,
+    };
+  }
+  return { phone: null, brief: trimmed };
+}
+
+/**
+ * Handle `/voice` — trigger an outbound voice call back to the requester.
+ * Imports lib/voice/outbound.mjs lazily so the slash command surface doesn't
+ * pull voice dependencies for agents that don't use voice.
+ *
+ * @param {object} payload          Slack slash_commands payload
+ * @param {object} ctx              { agentRoot, identity }
+ * @returns {Promise<{ok, message, response_type}>}
+ */
+export async function handleVoiceCommand(payload, ctx) {
+  const { agentRoot, identity } = ctx;
+  const { phone: explicitPhone, brief: argBrief } = parseVoiceArgs(payload.text);
+
+  let phone = explicitPhone;
+  if (!phone) {
+    phone = await resolvePhoneForSlackUser(agentRoot, payload.user_id);
+  }
+  if (!phone) {
+    return {
+      ok: false,
+      response_type: "ephemeral",
+      message: `:phone: I don't have a phone number for <@${payload.user_id}>. Try \`/voice +<E164>\` (e.g. \`/voice +14155551212\`) or add your number to \`config/contacts.yaml\` under \`phone:\`.`,
+    };
+  }
+
+  const brief = argBrief
+    || `Slack ${payload.user_name ? `${payload.user_name} ` : ""}requested a voice call from ${payload.channel_name ? `#${payload.channel_name}` : "Slack"}. Greet them by name and ask what they'd like to discuss.`;
+
+  // Lazy-import so non-voice agents don't pay the dependency cost.
+  let placeOutboundCall;
+  try {
+    ({ placeOutboundCall } = await import("../../../lib/voice/outbound.mjs"));
+  } catch (err) {
+    return {
+      ok: false,
+      response_type: "ephemeral",
+      message: `:warning: voice subsystem not available: ${err.message}. Run \`npx @cohortapp/agent-sdk init voice-realtime\`.`,
+    };
+  }
+
+  // Dispatch the call asynchronously — the slash command HTTP response is
+  // synchronous and Slack times out at 3s, so we fire-and-forget.
+  placeOutboundCall({
+    to: phone,
+    brief,
+    agentRoot,
+    identity,
+    peer_name: payload.user_name || null,
+    transport: process.env.VOICE_RELAY_URL ? "media_streams" : "sip",
+  })
+    .then((res) => {
+      // The placeOutboundCall result is logged inside that module; we don't
+      // need to do anything else here.
+      return res;
+    })
+    .catch((err) => {
+      // eslint-disable-next-line no-console
+      console.warn(`[/voice] placeOutboundCall failed for ${phone}: ${err.message}`);
+    });
+
+  return {
+    ok: true,
+    response_type: "ephemeral",
+    message: `:phone: Calling you at \`${phone}\` now${argBrief ? ` — brief: _${argBrief}_` : ""}. Pick up when it rings.`,
+  };
+}
+
+/**
+ * Master dispatcher — called by slack-socket-mode.mjs when an envelope of
+ * type=slash_commands arrives. Returns {ok, response_type, message} for the
+ * caller to POST to payload.response_url. Unknown commands return null so the
+ * caller can ignore (Slack will show "command not configured" to the user, which
+ * is the right UX — we don't want to claim ownership of every command).
+ */
+export async function handleSlashCommand(payload, ctx) {
+  const cmd = String(payload?.command || "").toLowerCase().trim();
+  switch (cmd) {
+    case "/voice":
+      return handleVoiceCommand(payload, ctx);
+    default:
+      return null;
+  }
+}
+
+/**
+ * POST the slash-command response back to Slack via response_url. Slack returns
+ * 200 quickly; we fire-and-forget if the URL is absent.
+ */
+export async function postSlashResponse(responseUrl, body) {
+  if (!responseUrl || !body) return;
+  try {
+    await fetch(responseUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        response_type: body.response_type || "ephemeral",
+        text: body.message || "",
+      }),
+    });
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(`[slash-command] failed to POST response_url: ${err.message}`);
+  }
+}

package/scripts/poller/secondary-gmail-poller.mjs

@@ -0,0 +1,132 @@
+// Principal Gmail Poller — polls the principal's inbox via native Node.js IMAP.
+// Uses the shared imap-client.mjs module.
+//
+// ACCESS BOUNDARY: This poller is only enabled for agents whose archetype
+// explicitly grants principal-Gmail access (typically Chief-of-Staff /
+// executive-operator archetypes). For other agents, leave
+// PRINCIPAL_GMAIL_APP_PASSWORD unset and this module will no-op.
+//
+// Backward compatibility: this file was previously named `secondary-gmail-poller.mjs`
+// with `pollSecondaryGmail` as the exported function. The new export name is
+// `pollPrincipalGmail`; the old name is re-exported as an alias.
+
+import { readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { AGENT_REPO_DIR, writeCursor } from "./utils.mjs";
+import { pollImapInbox } from "./imap-client.mjs";
+
+const INBOX_DIR = join(AGENT_REPO_DIR, "state", "inbox", "gmail");
+
+// Load principal identity from agent.json — email comes from there, password
+// from env (PRINCIPAL_GMAIL_APP_PASSWORD with MEHRAN_GMAIL_APP_PASSWORD fallback
+// for repos still on the legacy var name).
+function loadPrincipal() {
+  try {
+    const agent = JSON.parse(readFileSync(join(AGENT_REPO_DIR, "config/agent.json"), "utf-8"));
+    return agent.principal || {};
+  } catch {
+    return {};
+  }
+}
+
+function loadPrincipalPassword() {
+  if (process.env.PRINCIPAL_GMAIL_APP_PASSWORD) return process.env.PRINCIPAL_GMAIL_APP_PASSWORD;
+  if (process.env.MEHRAN_GMAIL_APP_PASSWORD) return process.env.MEHRAN_GMAIL_APP_PASSWORD;
+  try {
+    const envFile = readFileSync(join(AGENT_REPO_DIR, ".env"), "utf-8");
+    for (const line of envFile.split("\n")) {
+      const m = line.match(/^(PRINCIPAL_GMAIL_APP_PASSWORD|MEHRAN_GMAIL_APP_PASSWORD)=(.*)$/);
+      if (m) {
+        let val = m[2].trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
+        }
+        return val;
+      }
+    }
+  } catch { /* no .env file */ }
+  return "";
+}
+
+export async function pollPrincipalGmail() {
+  const items = [];
+  const errors = [];
+
+  const principal = loadPrincipal();
+  const principalEmail = principal.email;
+  const password = loadPrincipalPassword();
+
+  // No-op if not configured — agents without principal-Gmail access just
+  // skip this entirely instead of failing every poll cycle.
+  if (!principalEmail || !password) {
+    return { items, errors };
+  }
+
+  const accountSlug = (principal.firstName || "principal").toLowerCase();
+  const fileSuffix = `${accountSlug}-email`;
+
+  try {
+    const result = await pollImapInbox({
+      email: principalEmail,
+      password,
+      account: accountSlug,
+      fileSuffix,
+      eventType: `${accountSlug}_email`,
+      logPrefix: `[${accountSlug}-gmail]`,
+    });
+    if (result.errors.length > 0) {
+      errors.push(...result.errors);
+    }
+  } catch (err) {
+    const msg = `Principal Gmail poll failed: ${err.message}`;
+    console.error(`[${accountSlug}-gmail] ${msg}`);
+    errors.push(msg);
+  }
+
+  // Read resulting JSON files
+  try {
+    const fileGlob = `-${fileSuffix}.json`;
+    const files = readdirSync(INBOX_DIR).filter(
+      (f) => f.endsWith(fileGlob) && !f.endsWith(".processed"),
+    );
+
+    for (const file of files) {
+      try {
+        const content = readFileSync(join(INBOX_DIR, file), "utf-8");
+        const record = JSON.parse(content);
+
+        items.push({
+          id: file.replace(fileGlob, ""),
+          service: `${accountSlug}-gmail`,
+          channel: `${accountSlug}-inbox`,
+          sender: record.email?.from || "unknown",
+          sender_privilege: "unknown",
+          timestamp: record.received_at || new Date().toISOString(),
+          subject: record.email?.subject || "",
+          content: record.email?.snippet || "",
+          thread_id: record.email?.message_id || "",
+          is_reply: false,
+          priority_signals: {
+            from_ceo: false,
+            tagged_urgent: false,
+            contains_deadline: false,
+            mentions_agent: false,
+          },
+          raw_ref: `${accountSlug}-gmail:${record.email?.message_id || ""}`,
+        });
+      } catch (parseErr) {
+        errors.push(`Failed to parse ${file}: ${parseErr.message}`);
+      }
+    }
+  } catch (readErr) {
+    if (readErr.code !== "ENOENT") {
+      errors.push(`Failed to read inbox: ${readErr.message}`);
+    }
+  }
+
+  writeCursor(`${accountSlug}-gmail`, new Date().toISOString());
+  return { items, errors };
+}
+
+// Back-compat: old export name preserved so existing imports continue to work.
+export const pollSecondaryGmail = pollPrincipalGmail;