@cohortapp/agent-sdk 2.3.0

package/scripts/ci/check.test.mjs

@@ -0,0 +1,194 @@
+/**
+ * check.test.mjs — node:test coverage for the maestro CI guard scripts.
+ *
+ * Exercises the pure helpers (so logic is verified deterministically without
+ * depending on repo state) and asserts the aggregator + each guard return 0
+ * on the current, known-clean repo.
+ *
+ * Run: `node --test scripts/ci/check.test.mjs`
+ *
+ * @module scripts/ci/check.test
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  lineHasConflictMarker,
+  scanContentForMarkers,
+  findConflictMarkers,
+  run as runConflictMarkers,
+} from "./check-no-conflict-markers.mjs";
+import {
+  collectExportTargets,
+  flattenExports,
+  checkExportsExist,
+  run as runExportsExist,
+} from "./check-exports-exist.mjs";
+import {
+  isGlob,
+  checkFilesExist,
+  run as runFilesExist,
+} from "./check-files-exist.mjs";
+import {
+  scanText,
+  run as runNoConfidential,
+} from "./check-no-confidential.mjs";
+import { runAll, run as runAggregator, CHECKS } from "./check.mjs";
+
+// --- conflict markers: pure line matcher ---
+
+test("lineHasConflictMarker matches the four marker kinds", () => {
+  assert.equal(lineHasConflictMarker("<<<<<<< HEAD"), true);
+  assert.equal(lineHasConflictMarker("======="), true);
+  assert.equal(lineHasConflictMarker(">>>>>>> feature/x"), true);
+  assert.equal(lineHasConflictMarker("||||||| merged common ancestors"), true);
+  assert.equal(lineHasConflictMarker("======= \r".replace(" \r", "\r")), true); // CRLF bare marker
+});
+
+test("lineHasConflictMarker ignores look-alikes", () => {
+  assert.equal(lineHasConflictMarker("======== eight equals is a markdown rule"), false);
+  assert.equal(lineHasConflictMarker("===="), false);
+  assert.equal(lineHasConflictMarker("some =======text inline"), false);
+  assert.equal(lineHasConflictMarker(">>>>>>>>"), false);
+  assert.equal(lineHasConflictMarker(""), false);
+  assert.equal(lineHasConflictMarker(42), false);
+});
+
+test("scanContentForMarkers reports 1-based line numbers", () => {
+  const content = ["ok line", "<<<<<<< HEAD", "mine", "=======", "theirs", ">>>>>>> branch"].join("\n");
+  const hits = scanContentForMarkers(content);
+  assert.deepEqual(hits.map((h) => h.line), [2, 4, 6]);
+  assert.equal(hits[0].text, "<<<<<<< HEAD");
+});
+
+test("scanContentForMarkers clean content yields nothing", () => {
+  assert.deepEqual(scanContentForMarkers("nothing\nto\nsee\n"), []);
+  assert.deepEqual(scanContentForMarkers(""), []);
+});
+
+// --- exports flattening ---
+
+test("collectExportTargets handles string, array, nested conditions, and null", () => {
+  assert.deepEqual(collectExportTargets("./a.js", "./a"), [{ subpath: "./a", target: "./a.js" }]);
+  assert.deepEqual(collectExportTargets(null, "./blocked"), []);
+  const nested = { import: "./x.mjs", require: { default: "./x.cjs" } };
+  const got = collectExportTargets(nested, "./x").map((t) => t.target).sort();
+  assert.deepEqual(got, ["./x.cjs", "./x.mjs"]);
+  const arr = ["./first.js", { import: "./second.mjs" }];
+  const gotArr = collectExportTargets(arr, "./y").map((t) => t.target).sort();
+  assert.deepEqual(gotArr, ["./first.js", "./second.mjs"]);
+});
+
+test("flattenExports handles sugar string form and map form", () => {
+  assert.deepEqual(flattenExports("./index.js"), [{ subpath: ".", target: "./index.js" }]);
+  assert.deepEqual(flattenExports(undefined), []);
+  const pairs = flattenExports({ ".": "./i.js", "./t": "./t.js" });
+  assert.deepEqual(pairs.map((p) => p.target).sort(), ["./i.js", "./t.js"]);
+});
+
+// --- exports/files existence against a synthetic fixture repo ---
+
+async function makeFixtureRepo() {
+  const dir = await mkdtemp(path.join(tmpdir(), "maestro-ci-"));
+  await mkdir(path.join(dir, "lib"), { recursive: true });
+  await writeFile(path.join(dir, "lib", "real.js"), "export const x = 1;\n");
+  await writeFile(path.join(dir, "README.md"), "# fixture\n");
+  return dir;
+}
+
+test("checkExportsExist passes when targets exist, fails when missing", async () => {
+  const dir = await makeFixtureRepo();
+  try {
+    const good = await checkExportsExist({ cwd: dir, pkg: { exports: { ".": "./lib/real.js" } } });
+    assert.equal(good.ok, true);
+    assert.equal(good.checked, 1);
+
+    const bad = await checkExportsExist({ cwd: dir, pkg: { exports: { "./tts": "./lib/missing.mjs" } } });
+    assert.equal(bad.ok, false);
+    assert.equal(bad.missing.length, 1);
+    assert.equal(bad.missing[0].subpath, "./tts");
+
+    // null target is a deliberate block, not a missing file.
+    const blocked = await checkExportsExist({ cwd: dir, pkg: { exports: { "./x": null } } });
+    assert.equal(blocked.ok, true);
+    assert.equal(blocked.checked, 0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("isGlob detects metacharacters", () => {
+  assert.equal(isGlob("lib/"), false);
+  assert.equal(isGlob("README.md"), false);
+  assert.equal(isGlob("lib/**/*.js"), true);
+  assert.equal(isGlob("file?.js"), true);
+});
+
+test("checkFilesExist passes for present entries, fails for missing, skips globs", async () => {
+  const dir = await makeFixtureRepo();
+  try {
+    const good = await checkFilesExist({ cwd: dir, pkg: { files: ["lib/", "README.md"] } });
+    assert.equal(good.ok, true);
+    assert.equal(good.checked, 2);
+
+    const bad = await checkFilesExist({ cwd: dir, pkg: { files: ["lib/", "nope/"] } });
+    assert.equal(bad.ok, false);
+    assert.equal(bad.missing[0].entry, "nope/");
+
+    const globby = await checkFilesExist({ cwd: dir, pkg: { files: ["lib/**/*.js"] } });
+    assert.equal(globby.ok, true);
+    assert.equal(globby.skipped.length, 1);
+    assert.equal(globby.checked, 0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+// --- confidential-marker scanner: pure text matcher ---
+
+test("scanText flags denylisted markers and ignores clean text", () => {
+  const patterns = [
+    { label: "target", re: /\bAcme Capital\b/i },
+    { label: "id", re: /\bZZ9999\b/ },
+  ];
+  assert.deepEqual(scanText("nothing to see here", patterns), []);
+  assert.deepEqual(scanText("", patterns), []);
+  assert.deepEqual(scanText("some text", []), []);
+  assert.deepEqual(scanText(42, patterns), []);
+  const hits = scanText("we are pursuing acme capital (ref ZZ9999)", patterns);
+  assert.deepEqual(hits.map((h) => h.label).sort(), ["id", "target"]);
+});
+
+// --- conflict scan against a synthetic git-less dir is not possible (needs git);
+//     instead verify findConflictMarkers throws gracefully only via real repo run below.
+
+// --- live runs against the CURRENT maestro repo: must all be green ---
+
+test("each guard run() returns 0 on the current repo", async () => {
+  assert.equal(await runConflictMarkers(), 0);
+  assert.equal(await runExportsExist(), 0);
+  assert.equal(await runFilesExist(), 0);
+  assert.equal(await runNoConfidential(), 0);
+});
+
+test("findConflictMarkers finds nothing in the current repo", async () => {
+  const offenders = await findConflictMarkers();
+  assert.deepEqual(offenders, []);
+});
+
+test("aggregator runAll reports all checks passed on the current repo", async () => {
+  const { ok, results } = await runAll();
+  assert.equal(ok, true);
+  assert.equal(results.length, CHECKS.length);
+  assert.ok(results.every((r) => r.passed));
+});
+
+test("aggregator run() exits 0 on the current repo", async () => {
+  assert.equal(await runAggregator(), 0);
+});

package/scripts/ci/run-coverage.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * run-coverage.mjs — coverage variant of the maestro test runner (audit L31).
+ *
+ * Uses the SAME test discovery as scripts/ci/run-tests.mjs (every `*.test.mjs`
+ * under lib/, scripts/, and bin/), but invokes `node --test` with
+ * `--experimental-test-coverage` so contributors can see line/branch/function
+ * coverage for the suite.
+ *
+ * This is intentionally NOT wired into `npm test` or the CI publish gate: the
+ * experimental coverage reporter is comparatively slow and its output format is
+ * not yet stable across Node minors, so gating CI on it would add flakiness for
+ * no safety gain. It is a developer convenience — run it locally with
+ * `npm run test:coverage`.
+ *
+ * Node builtins only (maestro is "type":"module", near-zero-dep by design).
+ * Requires Node 20+ (already enforced via package.json engines), which is where
+ * `--experimental-test-coverage` is available.
+ *
+ * Usage: `node scripts/ci/run-coverage.mjs`
+ *   exit 0 → all tests passed; non-zero → at least one failed (or none found).
+ *
+ * @module scripts/ci/run-coverage
+ */
+
+import { readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ROOTS = ["lib", "scripts", "bin"];
+const SKIP_DIRS = new Set(["node_modules", ".git", "state", "logs", "audit"]);
+
+/**
+ * Recursively collect `*.test.mjs` files under `dir` (absolute). Mirrors the
+ * discovery in run-tests.mjs so coverage runs over the exact same set.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findTests(dir) {
+  let out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // missing root dir is fine
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out = out.concat(findTests(join(dir, entry.name)));
+    } else if (entry.isFile() && entry.name.endsWith(".test.mjs")) {
+      out.push(join(dir, entry.name));
+    }
+  }
+  return out;
+}
+
+const files = ROOTS.flatMap((r) => findTests(join(REPO_ROOT, r))).sort();
+
+if (files.length === 0) {
+  console.error("run-coverage: no *.test.mjs files found — refusing to report success.");
+  process.exit(1);
+}
+
+console.log(`run-coverage: discovered ${files.length} test file(s).`);
+
+const result = spawnSync(
+  process.execPath,
+  ["--test", "--experimental-test-coverage", ...files],
+  {
+    cwd: REPO_ROOT,
+    stdio: "inherit",
+  },
+);
+
+if (result.error) {
+  console.error("run-coverage: failed to launch node --test:", result.error.message);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/scripts/ci/run-tests.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * run-tests.mjs — discovery test runner for maestro.
+ *
+ * Recursively finds every `*.test.mjs` under lib/, scripts/, and bin/ and runs
+ * them with `node --test`. Replaces the previous hand-enumerated file list in
+ * package.json, which silently excluded any new test until it was manually
+ * appended (audit L25). A renamed/deleted file can no longer error the whole
+ * invocation, and a newly added test is picked up automatically.
+ *
+ * Node builtins only (maestro is "type":"module", near-zero-dep by design).
+ *
+ * Usage: `node scripts/ci/run-tests.mjs`
+ *   exit 0 → all tests passed; non-zero → at least one failed (or none found).
+ *
+ * @module scripts/ci/run-tests
+ */
+
+import { readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ROOTS = ["lib", "scripts", "bin", "services"];
+const SKIP_DIRS = new Set(["node_modules", ".git", "state", "logs", "audit"]);
+
+/**
+ * Recursively collect `*.test.mjs` files under `dir` (absolute), returning
+ * paths relative to REPO_ROOT for stable, readable output.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findTests(dir) {
+  let out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out; // missing root dir is fine
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out = out.concat(findTests(join(dir, entry.name)));
+    } else if (entry.isFile() && entry.name.endsWith(".test.mjs")) {
+      out.push(join(dir, entry.name));
+    }
+  }
+  return out;
+}
+
+const files = ROOTS.flatMap((r) => findTests(join(REPO_ROOT, r))).sort();
+
+if (files.length === 0) {
+  console.error("run-tests: no *.test.mjs files found — refusing to report success.");
+  process.exit(1);
+}
+
+console.log(`run-tests: discovered ${files.length} test file(s).`);
+
+const result = spawnSync(process.execPath, ["--test", ...files], {
+  cwd: REPO_ROOT,
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error("run-tests: failed to launch node --test:", result.error.message);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/scripts/cloud-relay/README.md

@@ -0,0 +1,59 @@
+# Cloud Relay — Slack Events to Mac mini
+
+Public HTTPS service that proxies Slack Events API webhooks into a
+Mac-mini-resident maestro daemon over Server-Sent Events.
+
+## Why
+
+Slack Socket Mode only delivers events for the **bot user** that owns the
+app. DMs sent to the agent's underlying **user account** (e.g.,
+`U099N1JE0LA` for Ravi) are invisible to Socket Mode — the bot is not a
+member of those conversations. To get real-time push for those DMs we
+need user-scope event subscriptions, which require an HTTPS endpoint, and
+Mac minis don't have public IPs. This relay closes the gap.
+
+## Architecture
+
+```
+  Slack ──HTTPS POST──▶ Railway (this relay) ──SSE──▶ Mac mini (slack-cloud-relay-client.mjs)
+                              │                          │
+                              │                          └──▶ writeInboxItem() → state/inbox/slack/
+                              │
+                              └── verifies x-slack-signature, fans events to all SSE clients
+```
+
+## Deploy
+
+```
+cd scripts/cloud-relay
+railway init
+railway up
+railway variables set \
+  SLACK_SIGNING_SECRET=<from Slack app Basic Information> \
+  RELAY_SHARED_SECRET=<long random string, share with Mac mini>
+railway domain          # → returns https://<project>.up.railway.app
+```
+
+Then in the Slack app config:
+1. Event Subscriptions → Enable Events → set Request URL to
+   `https://<project>.up.railway.app/slack/events`.
+2. Subscribe to **User events** (`message.im`, `message.mpim`,
+   `message.channels`, `message.groups`, `app_mention`).
+3. Save changes and reinstall the app.
+
+Set the Mac mini's `.env`:
+```
+CLOUD_RELAY_URL=https://<project>.up.railway.app
+RELAY_SHARED_SECRET=<same string as on Railway>
+```
+
+## Endpoints
+
+- `POST /slack/events` — Slack Events API. Verifies `x-slack-signature`
+  using `SLACK_SIGNING_SECRET`; responds to `url_verification` challenges;
+  fans event callbacks out to connected SSE clients.
+- `GET /events/stream` — SSE stream. Requires
+  `Authorization: Bearer <RELAY_SHARED_SECRET>`. New connections receive
+  the last 100 events as catch-up; heartbeats every 25 s keep the stream
+  alive through proxies.
+- `GET /health` — Liveness probe (returns connection + queue counts).

package/scripts/cloud-relay/index.mjs

@@ -0,0 +1,233 @@
+/**
+ * Maestro — Slack Events Cloud Relay
+ *
+ * Public HTTPS service (deployed on Railway) that bridges Slack user-scope
+ * Events API webhooks into a Mac-mini-resident maestro daemon over SSE.
+ *
+ * Why this exists: Socket Mode is bot-scoped, so DMs sent to the agent's
+ * USER account (not its bot user) are invisible to a Socket Mode listener.
+ * To get real-time push for those DMs, the Slack app needs user-scope event
+ * subscriptions, which require an HTTPS webhook URL — and Mac minis don't
+ * have public IPs. This relay sits in front: Slack POSTs events here, the
+ * Mac mini holds an authenticated SSE connection, and events get pushed
+ * back over the open stream in milliseconds.
+ *
+ * Endpoints:
+ *   POST /slack/events     — Slack Events API receiver. Verifies the v0
+ *                            HMAC signature, handles url_verification on
+ *                            registration, fans event_callback envelopes
+ *                            out to every connected SSE client.
+ *   GET  /events/stream    — Server-Sent Events feed for Mac-mini clients
+ *                            holding an open connection. Bearer-token
+ *                            authenticated against RELAY_SHARED_SECRET.
+ *                            New connections receive the last ~100 events
+ *                            so a brief disconnect doesn't drop messages.
+ *   GET  /health           — Liveness probe used by Railway / external
+ *                            uptime monitors.
+ *
+ * Env (all required):
+ *   PORT                   — provided by Railway
+ *   SLACK_SIGNING_SECRET   — from Slack app "Basic Information" page
+ *   RELAY_SHARED_SECRET    — operator-chosen long random string; the Mac
+ *                            mini client must send the same value in its
+ *                            Authorization: Bearer <...> header
+ */
+
+import http from "node:http";
+import crypto from "node:crypto";
+
+const PORT = parseInt(process.env.PORT || "3100", 10);
+const SIGNING_SECRET = process.env.SLACK_SIGNING_SECRET || "";
+const RELAY_SHARED_SECRET = process.env.RELAY_SHARED_SECRET || "";
+
+if (!SIGNING_SECRET) {
+  console.error("FATAL: SLACK_SIGNING_SECRET env var is required");
+  process.exit(78);
+}
+if (!RELAY_SHARED_SECRET) {
+  console.error("FATAL: RELAY_SHARED_SECRET env var is required");
+  process.exit(78);
+}
+
+// Connected Mac-mini SSE clients (typically 1, but designed for fan-out).
+const sseClients = new Set();
+
+// Bounded ring buffer of recent events for reconnect replay. Slack-side
+// "retry on 5xx" already gives us at-least-once delivery, so this is just
+// for the case where the Mac mini's SSE connection drops between an event
+// arriving and being acked: when it reconnects within ~5 minutes it gets
+// the missing events replayed instead of waiting for Slack's next retry.
+const REPLAY_CAPACITY = 100;
+const eventQueue = [];
+
+function log(level, message, data) {
+  const ts = new Date().toISOString();
+  const line = JSON.stringify({ ts, level, message, ...(data || {}) });
+  if (level === "error") console.error(line);
+  else console.log(line);
+}
+
+/**
+ * Verify Slack's v0 HMAC signature. Per Slack docs:
+ *   sig_basestring = "v0:" + timestamp + ":" + raw_body
+ *   expected       = "v0=" + hex(hmac_sha256(SIGNING_SECRET, sig_basestring))
+ * Also enforce the 5-minute timestamp window to block replay attacks.
+ */
+function verifySlackSignature(timestamp, body, signature) {
+  if (!timestamp || !signature) return false;
+  const tsNum = parseInt(timestamp, 10);
+  if (!Number.isFinite(tsNum)) return false;
+  const ageSec = Math.abs(Date.now() / 1000 - tsNum);
+  if (ageSec > 5 * 60) return false;
+  const basestring = `v0:${timestamp}:${body}`;
+  const expected = `v0=${crypto.createHmac("sha256", SIGNING_SECRET).update(basestring).digest("hex")}`;
+  if (expected.length !== signature.length) return false;
+  try {
+    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
+  } catch {
+    return false;
+  }
+}
+
+function fanOut(envelope) {
+  eventQueue.push(envelope);
+  if (eventQueue.length > REPLAY_CAPACITY) eventQueue.shift();
+  const data = `data: ${JSON.stringify(envelope)}\n\n`;
+  const dead = [];
+  for (const client of sseClients) {
+    try {
+      client.write(data);
+    } catch {
+      dead.push(client);
+    }
+  }
+  for (const c of dead) sseClients.delete(c);
+  log("info", "fanned-out", { sse_clients: sseClients.size, queue_size: eventQueue.length });
+}
+
+const server = http.createServer((req, res) => {
+  // Health probe
+  if (req.method === "GET" && req.url === "/health") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+      ok: true,
+      sse_clients: sseClients.size,
+      queue_size: eventQueue.length,
+      uptime_s: Math.round(process.uptime()),
+    }));
+    return;
+  }
+
+  // Slack Events API endpoint
+  if (req.method === "POST" && req.url === "/slack/events") {
+    let body = "";
+    req.on("data", (chunk) => { body += chunk; });
+    req.on("end", () => {
+      const ts = req.headers["x-slack-request-timestamp"];
+      const sig = req.headers["x-slack-signature"];
+
+      if (!verifySlackSignature(ts, body, sig)) {
+        log("warn", "rejected-bad-signature", { ts_header: !!ts });
+        res.writeHead(401, { "Content-Type": "text/plain" });
+        res.end("invalid signature");
+        return;
+      }
+
+      let payload;
+      try {
+        payload = JSON.parse(body);
+      } catch {
+        res.writeHead(400, { "Content-Type": "text/plain" });
+        res.end("bad json");
+        return;
+      }
+
+      // One-time URL verification when the operator first registers the
+      // webhook in the Slack app config. Slack expects an echo of the
+      // `challenge` field within 3 seconds.
+      if (payload.type === "url_verification") {
+        log("info", "url-verification-challenge", { challenge_len: (payload.challenge || "").length });
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ challenge: payload.challenge }));
+        return;
+      }
+
+      // Event callback. Slack requires a 200 within 3 seconds or it
+      // retries, so ack immediately and fan out after.
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.end("ok");
+      if (payload.type === "event_callback") {
+        fanOut(payload);
+      } else {
+        log("info", "ignored-envelope-type", { type: payload.type });
+      }
+    });
+    req.on("error", (err) => {
+      log("error", "request-error", { error: err.message });
+    });
+    return;
+  }
+
+  // SSE stream to Mac mini
+  if (req.method === "GET" && req.url === "/events/stream") {
+    const auth = req.headers.authorization || "";
+    const want = `Bearer ${RELAY_SHARED_SECRET}`;
+    if (auth.length !== want.length || !crypto.timingSafeEqual(Buffer.from(auth), Buffer.from(want))) {
+      res.writeHead(401, { "Content-Type": "text/plain" });
+      res.end("unauthorized");
+      return;
+    }
+
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      "Connection": "keep-alive",
+      "X-Accel-Buffering": "no",
+    });
+    res.write(": connected\n\n");
+    sseClients.add(res);
+    log("info", "sse-client-connected", { sse_clients: sseClients.size, remote: req.socket.remoteAddress });
+
+    // Replay the recent backlog so a brief disconnect doesn't drop events.
+    for (const ev of eventQueue) {
+      try { res.write(`data: ${JSON.stringify(ev)}\n\n`); } catch { /* */ }
+    }
+
+    // Heartbeat — many proxies idle-timeout long-lived streams; a comment
+    // line every 25s keeps the connection visibly alive without polluting
+    // the event payloads.
+    const hb = setInterval(() => {
+      try {
+        res.write(": hb\n\n");
+      } catch {
+        clearInterval(hb);
+      }
+    }, 25_000);
+
+    req.on("close", () => {
+      sseClients.delete(res);
+      clearInterval(hb);
+      log("info", "sse-client-disconnected", { sse_clients: sseClients.size });
+    });
+    return;
+  }
+
+  res.writeHead(404, { "Content-Type": "text/plain" });
+  res.end("not found");
+});
+
+server.listen(PORT, () => {
+  log("info", "cloud-relay-listening", { port: PORT });
+});
+
+// Graceful shutdown on SIGTERM (Railway sends this on redeploy / scale-down).
+const shutdown = (signal) => {
+  log("info", "shutdown-requested", { signal });
+  for (const client of sseClients) {
+    try { client.end(); } catch { /* */ }
+  }
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(0), 5_000).unref();
+};
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));

package/scripts/cloud-relay/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@cohortapp/agent-sdk-cloud-relay",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Public HTTPS relay that proxies Slack Events API into a Mac-mini-resident maestro daemon over SSE.",
+  "main": "index.mjs",
+  "scripts": {
+    "start": "node index.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/scripts/cloud-relay/railway.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "NIXPACKS"
+  },
+  "deploy": {
+    "startCommand": "node index.mjs",
+    "healthcheckPath": "/health",
+    "healthcheckTimeout": 100,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10
+  }
+}