@cohortapp/agent-sdk 2.3.0

package/lib/channels/registry.mjs

@@ -0,0 +1,164 @@
+/**
+ * Maestro — Channel registry
+ *
+ * Lightweight in-process registry for channel plugins. Each channel
+ * registers itself via `registerChannel(name, factory, capabilities)`
+ * and the daemon can later iterate over registered channels to:
+ *   - start their inbound listeners
+ *   - send outbound replies to the right channel
+ *   - feature-detect (e.g. "does this channel support voice notes?")
+ *
+ * Channels are NOT auto-discovered on the filesystem in this minimal
+ * v1 — the operator wires them up explicitly in
+ * `scripts/daemon/maestro-daemon.mjs` (or a new
+ * `scripts/daemon/channel-bus.mjs` worker). Auto-discovery via
+ * config/channels/*.yaml can come later without breaking changes.
+ *
+ * The registry is a singleton so any code path can reach it.
+ */
+
+import { validateChannel } from "./channel.mjs";
+
+const _channels = new Map(); // name → { instance, factory, capabilities }
+
+/**
+ * Register a channel instance.
+ *
+ * Registering a name that is already present is a programming error by
+ * default — silently overwriting the previous channel would orphan its
+ * running listener and leak it. Pass `{ replace: true }` to deliberately
+ * swap a channel; in that case the previous instance's `stop()` is
+ * awaited (best-effort) before the new one takes its place.
+ *
+ * @param {string} name
+ * @param {object} channelInstance  Conforming to the Channel interface
+ * @param {object} [opts]
+ * @param {boolean} [opts.replace=false]  Replace an existing channel of the same name.
+ * @returns {Promise<void>|void}  A promise when replacing (so the old stop() is awaited), otherwise void.
+ */
+export function registerChannel(name, channelInstance, opts = {}) {
+  if (!name || typeof name !== "string") throw new Error("registerChannel: name required");
+  validateChannel(channelInstance);
+  const existing = _channels.get(name);
+  if (existing && !opts.replace) {
+    throw new Error(
+      `registerChannel: channel "${name}" already registered; pass { replace: true } to override`
+    );
+  }
+  const set = () =>
+    _channels.set(name, {
+      instance: channelInstance,
+      capabilities: channelInstance.capabilities || [],
+    });
+  if (existing && opts.replace) {
+    // Stop the previous instance before swapping so its listener does not
+    // leak. Best-effort: a failing stop() must not block the replacement.
+    return Promise.resolve()
+      .then(() => existing.instance.stop?.())
+      .catch(() => {})
+      .then(set);
+  }
+  set();
+}
+
+export function getChannel(name) {
+  return _channels.get(name)?.instance;
+}
+
+export function listChannels() {
+  return Array.from(_channels.keys()).sort();
+}
+
+export function findChannelsWithCapability(cap) {
+  const out = [];
+  for (const [name, entry] of _channels.entries()) {
+    if (entry.capabilities.includes(cap)) out.push(name);
+  }
+  return out;
+}
+
+export function clearChannels() {
+  _channels.clear();
+}
+
+/**
+ * Start all registered channels concurrently and wire their inbound
+ * messages through a single onInbound handler. Returns a teardown fn.
+ *
+ * Per-channel start results are surfaced two ways so a failing start is
+ * never swallowed:
+ *   - the returned teardown fn carries `.results` (array of
+ *     `{ name, ok, error? }`), and
+ *   - `opts.onError(name, err)` is invoked for each failure if supplied.
+ * Both synchronous throws and rejected start() promises are captured.
+ *
+ * The teardown fn only stops channels that actually started, so we never
+ * call `stop()` on a channel whose `start()` failed (which would otherwise
+ * trip on half-initialised state).
+ *
+ * @param {(msg: import("./channel.mjs").ChannelMessage) => void} onInbound
+ * @param {object} [opts]
+ * @param {(name: string, err: Error) => void} [opts.onError]
+ * @returns {Promise<(() => Promise<void>) & { results: Array<{name:string,ok:boolean,error?:Error}> }>}
+ */
+export async function startAllChannels(onInbound, opts = {}) {
+  if (typeof onInbound !== "function") throw new Error("startAllChannels: onInbound required");
+  const controller = new AbortController();
+  const started = new Set(); // names whose start() resolved successfully
+  const pending = [];
+  const results = [];
+  for (const [name, entry] of _channels.entries()) {
+    let p;
+    try {
+      p = Promise.resolve(
+        entry.instance.start({
+          onInbound: (msg) => {
+            // Stamp the channel name in case the implementation forgot.
+            if (!msg.channel) msg.channel = name;
+            onInbound(msg);
+          },
+          signal: controller.signal,
+          ...(opts.channelOpts?.[name] || {}),
+        })
+      );
+    } catch (err) {
+      // Synchronous throw from start().
+      results.push({ name, ok: false, error: err });
+      if (typeof opts.onError === "function") opts.onError(name, err);
+      continue;
+    }
+    pending.push(
+      p.then(
+        () => {
+          started.add(name);
+          results.push({ name, ok: true });
+        },
+        (err) => {
+          // Asynchronous rejection from start().
+          results.push({ name, ok: false, error: err });
+          if (typeof opts.onError === "function") opts.onError(name, err);
+        }
+      )
+    );
+  }
+  await Promise.all(pending);
+  const stopAll = async function stopAll() {
+    controller.abort();
+    await Promise.allSettled(
+      Array.from(started).map((name) =>
+        Promise.resolve().then(() => _channels.get(name)?.instance.stop?.())
+      )
+    );
+  };
+  stopAll.results = results;
+  return stopAll;
+}
+
+export default {
+  registerChannel,
+  getChannel,
+  listChannels,
+  findChannelsWithCapability,
+  clearChannels,
+  startAllChannels,
+};

package/lib/channels/slack/adapter.mjs

@@ -0,0 +1,317 @@
+/**
+ * Maestro — Slack channel adapter (Socket Mode, re-homed translation)
+ *
+ * WS2 (design §5) makes the channel layer the *live* Slack ingestion path
+ * without a big-bang rewrite. This adapter:
+ *
+ *   - extends BaseAdapter (pairingMode "open" — Slack membership + self/peer
+ *     filtering already happen in `shouldKeepEvent`, and the daemon's
+ *     directed-gate governs the rest, so default-deny pairing must NOT apply
+ *     to the live Slack path or it would drop the principal's DMs);
+ *   - drives the *real* `createSocketModeClient` from
+ *     scripts/poller/slack-socket-mode.mjs in `_connect` (the connection, ack,
+ *     reconnect, and emergency-stop logic are unchanged);
+ *   - re-homes the legacy `eventToInboxItem` translation: the socket client's
+ *     `writeInbox` injection is redirected so each kept event becomes a
+ *     MessageEvent (`inboxItemToEvent`) flowing through BaseAdapter → onInbound;
+ *     the daemon's onInbound re-serializes via `eventToInboxItem` →
+ *     `writeInboxItem`. Net effect on disk: identical bytes for message events,
+ *     plus populated `kind` / `source` / `thread_context`.
+ *   - closes the 3 Slack gaps via an `enrich` hook (uses the bot token):
+ *       (a) reactions → kind:"reaction" (target text via conversations.history)
+ *       (b) thread replies → thread_context via conversations.replies
+ *       (c) cc_channels → kind:"channel_cc" (opt-in, config/slack.yaml)
+ *
+ * The existing send/react/healthCheck (script-backed) are preserved so the
+ * channel bus + channels.test.mjs keep working.
+ *
+ * @module lib/channels/slack/adapter
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CHANNEL_CAPABILITIES } from "../channel.mjs";
+import { BaseAdapter } from "../base-adapter.mjs";
+import { definePlatform } from "../contract.mjs";
+import { inboxItemToEvent } from "../inbox-item.mjs";
+import {
+  createSocketModeClient,
+  loadAgentIdentity,
+  loadPeerSlackIds,
+  loadEnvFromFile,
+} from "../../../scripts/poller/slack-socket-mode.mjs";
+
+const DEFAULT_CAPABILITIES = [
+  CHANNEL_CAPABILITIES.SEND,
+  CHANNEL_CAPABILITIES.REACT,
+  CHANNEL_CAPABILITIES.THREAD,
+  CHANNEL_CAPABILITIES.MEDIA_IMAGE,
+  CHANNEL_CAPABILITIES.MEDIA_DOCUMENT,
+  CHANNEL_CAPABILITIES.MENTIONS,
+  CHANNEL_CAPABILITIES.RICH_BLOCKS,
+  CHANNEL_CAPABILITIES.GROUP_CHAT,
+];
+
+const SLACK_API = "https://slack.com/api";
+
+export class SlackAdapter extends BaseAdapter {
+  constructor(opts = {}) {
+    super({ name: "slack", capabilities: DEFAULT_CAPABILITIES, pairingMode: "open", ...opts });
+    this.sendScript = opts.sendScript || join(this.agentRoot, "scripts/slack-send.sh");
+    this._client = null;
+    this._slackConfig = opts.slackConfig || loadSlackConfig(this.agentRoot);
+    this._ccChannels = new Set(this._slackConfig.cc_channels || []);
+    this._reactionsOn = this._slackConfig.reactions !== false; // default on
+    this._botToken = opts.botToken || process.env.SLACK_BOT_TOKEN || "";
+    this._fetchFn = opts.fetchFn || globalThis.fetch;
+    // Injection seams for tests.
+    this._createClient = opts.createClient || createSocketModeClient;
+  }
+
+  /**
+   * `_connect` drives the real Socket Mode client. The client's `writeInbox`
+   * callback is redirected here: instead of writing the inbox item itself, it
+   * hands the item to the adapter, which converts it to a MessageEvent and
+   * lets BaseAdapter forward it to onInbound. The daemon's onInbound performs
+   * the actual `writeInboxItem`, so there is exactly one write per event.
+   */
+  async _connect({ onRaw, signal }) {
+    loadEnvFromFile(this.agentRoot);
+    const identity = this._identity || loadAgentIdentity(this.agentRoot);
+    const peerSlackIds = this._peerSlackIds || loadPeerSlackIds(this.agentRoot, identity.slackMemberId);
+    if (!this._botToken) this._botToken = process.env.SLACK_BOT_TOKEN || "";
+    const appToken = this._appToken || process.env.SLACK_APP_LEVEL_TOKEN || "";
+
+    // The socket client emits legacy inbox items via writeInbox. We funnel
+    // them through onRaw so BaseAdapter.start's _toEvent → pairing-gate →
+    // onInbound pipeline runs uniformly. `_toEvent` is identity here (the item
+    // was already turned into a MessageEvent by the writeInbox shim).
+    const writeInbox = (service, item) => {
+      try {
+        const ev = inboxItemToEvent(item);
+        ev.channel = "slack";
+        onRaw(ev);
+      } catch (err) {
+        this.log("error", `slack item→event failed: ${err.message}`);
+      }
+    };
+
+    this._client = this._createClient({
+      agentRoot: this.agentRoot,
+      appToken,
+      identity,
+      peerSlackIds,
+      writeInbox,
+      reactions: this._reactionsOn,
+      ccChannels: this._ccChannels.size ? this._ccChannels : null,
+      enrich: (envelope) => this._enrich(envelope),
+      ...(this._clientOpts || {}),
+    });
+    await this._client.start();
+    if (signal) signal.addEventListener?.("abort", () => { try { this._client?.stop(); } catch { /* */ } });
+  }
+
+  // The writeInbox shim already produced a MessageEvent; _toEvent is identity.
+  _toEvent(raw) {
+    return raw || null;
+  }
+
+  /**
+   * Resolve enrichment for a kept event before translation:
+   *   - reaction → fetch the target message text (conversations.history)
+   *   - thread reply → fetch the prior thread history (conversations.replies)
+   * Returns `{ threadContext }` consumed by eventToInboxItem. Fail-open: any
+   * error returns `{}` so the event still flows (without context).
+   */
+  async _enrich(envelope) {
+    const event = envelope?.payload?.event;
+    if (!event || !this._botToken) return {};
+    try {
+      if (event.type === "reaction_added" || event.type === "reaction_removed") {
+        const targetText = await this._fetchMessageText(event.item?.channel, event.item?.ts);
+        return targetText ? { threadContext: targetText } : {};
+      }
+      if (event.type === "message") {
+        const threadTs = event.thread_ts || "";
+        const isReply = !!threadTs && threadTs !== event.ts;
+        if (isReply) {
+          const ctx = await this._fetchThreadContext(event.channel, threadTs, event.ts);
+          return ctx ? { threadContext: ctx } : {};
+        }
+      }
+    } catch (err) {
+      this.log("warn", `enrich failed (fail-open): ${err.message}`);
+    }
+    return {};
+  }
+
+  async _slackGet(method, params) {
+    const url = new URL(`${SLACK_API}/${method}`);
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, String(v));
+    const res = await this._fetchFn(url, { headers: { Authorization: `Bearer ${this._botToken}` } });
+    return res.json();
+  }
+
+  async _fetchMessageText(channel, ts) {
+    if (!channel || !ts) return "";
+    const body = await this._slackGet("conversations.history", { channel, latest: ts, oldest: ts, inclusive: true, limit: 1 });
+    if (!body.ok || !Array.isArray(body.messages) || body.messages.length === 0) return "";
+    return (body.messages[0].text || "").slice(0, 1000);
+  }
+
+  async _fetchThreadContext(channel, threadTs, beforeTs) {
+    if (!channel || !threadTs) return "";
+    const body = await this._slackGet("conversations.replies", { channel, ts: threadTs, limit: 20 });
+    if (!body.ok || !Array.isArray(body.messages)) return "";
+    const before = parseFloat(beforeTs);
+    const agentFirst = (this._identity?.firstName || loadAgentIdentity(this.agentRoot).firstName || "Agent");
+    return body.messages
+      .filter((m) => !beforeTs || parseFloat(m.ts) < before)
+      .map((m) => {
+        const who = m.bot_id ? "bot" : (m.user || "user");
+        return `${who}: ${(m.text || "").slice(0, 500)}`;
+      })
+      .join("\n");
+  }
+
+  // -- outbound (script-backed, preserved from the v1 adapter) ---------------
+
+  async _send(out) {
+    if (!out || !out.to) throw new Error("Slack.send: msg.to required");
+    if (!existsSync(this.sendScript)) {
+      throw new Error(`Slack.send: ${this.sendScript} not found; install maestro scripts first`);
+    }
+    const args = [out.to, "--text", out.text || ""];
+    const threadRef = out.thread_ref ?? out.source?.threadRef;
+    if (threadRef) args.push("--thread", String(threadRef));
+    if (out.blocks) args.push("--blocks", JSON.stringify(out.blocks));
+    try {
+      const stdout = execFileSync(this.sendScript, args, {
+        encoding: "utf-8",
+        timeout: 30_000,
+        env: { ...process.env, AGENT_ROOT: this.agentRoot, AGENT_DIR: this.agentRoot },
+      });
+      const tsMatch = stdout.match(/ts=([0-9.]+)/);
+      return { ok: true, message_id: tsMatch?.[1] || "", raw: { stdout } };
+    } catch (err) {
+      const stderr = err.stderr?.toString?.() || err.message;
+      throw new Error(`Slack.send failed: ${stderr}`);
+    }
+  }
+
+  async _react({ messageRef, emoji }) {
+    const reactScript = join(this.agentRoot, "scripts/slack-react.sh");
+    if (!existsSync(reactScript)) {
+      this.log("warn", "scripts/slack-react.sh not present — reaction skipped");
+      return { ok: false, error: "react-script-missing" };
+    }
+    execFileSync(reactScript, [String(messageRef), emoji], {
+      encoding: "utf-8",
+      timeout: 10_000,
+      env: { ...process.env, AGENT_ROOT: this.agentRoot, AGENT_DIR: this.agentRoot },
+    });
+    return { ok: true };
+  }
+
+  async _setTyping(source, on) {
+    // Slack typing via assistant.threads.setStatus requires the bot token +
+    // an assistant-enabled app; best-effort and fail-open. Only meaningful for
+    // on=true (Slack clears status when the next message posts).
+    if (!on || !this._botToken) return;
+    const channel = source?.chatId;
+    const threadTs = source?.threadRef;
+    if (!channel || !threadTs) return; // setStatus is thread-scoped
+    try {
+      await this._fetchFn(`${SLACK_API}/assistant.threads.setStatus`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${this._botToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ channel_id: channel, thread_ts: threadTs, status: "is typing…" }),
+      });
+    } catch { /* fail-open */ }
+  }
+
+  async healthCheck() {
+    const present = existsSync(this.sendScript);
+    return { ok: present, detail: present ? "slack-send.sh present" : `missing ${this.sendScript}` };
+  }
+
+  async stop() {
+    await super.stop();
+    try { this._client?.stop(); } catch { /* */ }
+    this._client = null;
+  }
+}
+
+/** Load config/slack.yaml (cc_channels, reactions, ingest mode). Best-effort. */
+export function loadSlackConfig(agentRoot) {
+  const path = join(resolve(agentRoot || "."), "config/slack.yaml");
+  if (!existsSync(path)) return {};
+  try {
+    const body = readFileSync(path, "utf-8");
+    return parseSlackConfig(body);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Tiny dependency-free parser for the slack.yaml subset we need
+ * (`ingest_mode`, `reactions`, `cc_channels: [..]` or list items). Avoids a
+ * dynamic js-yaml import on the channel hot path.
+ */
+export function parseSlackConfig(body) {
+  const out = {};
+  let inCc = false;
+  for (const raw of String(body).split("\n")) {
+    const line = raw.replace(/\t/g, "  ");
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const ingest = line.match(/^ingest_mode:\s*(\S+)/);
+    if (ingest) { out.ingest_mode = unquote(ingest[1]); inCc = false; continue; }
+    const reactions = line.match(/^reactions:\s*(\S+)/);
+    if (reactions) { out.reactions = /^(true|on|yes)$/i.test(unquote(reactions[1])); inCc = false; continue; }
+    const ccInline = line.match(/^cc_channels:\s*\[(.*)\]\s*$/);
+    if (ccInline) {
+      out.cc_channels = ccInline[1].split(",").map((s) => unquote(s.trim())).filter(Boolean);
+      inCc = false;
+      continue;
+    }
+    if (/^cc_channels:\s*$/.test(line)) { out.cc_channels = out.cc_channels || []; inCc = true; continue; }
+    const item = line.match(/^\s*-\s*(.+)$/);
+    if (inCc && item) { out.cc_channels.push(unquote(item[1].trim())); continue; }
+    if (!/^\s/.test(line)) inCc = false; // a new top-level key closes the list
+  }
+  return out;
+}
+
+function unquote(s) {
+  let t = String(s).trim();
+  // strip inline comment for unquoted
+  if (!(t.startsWith('"') || t.startsWith("'"))) {
+    const h = t.indexOf("#");
+    if (h >= 0) t = t.slice(0, h).trim();
+  }
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) t = t.slice(1, -1);
+  return t;
+}
+
+/** Factory matching the channel/platform contract. */
+export function createSlackChannel(opts = {}) {
+  return new SlackAdapter(opts);
+}
+
+// Self-register so the platform registry knows about Slack (factory + gate
+// file + capabilities). NOTE (single-owner rule, H2): the maestro daemon's
+// generic channel loop DELIBERATELY SKIPS Slack — Slack's real-time connection
+// is owned solely by the dedicated launchd `slack-socket` process
+// (scripts/poller/slack-socket-mode.mjs), which reads config/slack.yaml itself.
+// Starting Slack here too would double-ingest every DM. This registration is
+// still used by tests + any non-daemon caller that wants the adapter factory.
+definePlatform({
+  name: "slack",
+  gateFile: "config/slack.yaml",
+  factory: createSlackChannel,
+  capabilities: DEFAULT_CAPABILITIES,
+});
+
+export default createSlackChannel;

package/lib/channels/slack-adapter.test.mjs

@@ -0,0 +1,212 @@
+/**
+ * slack-adapter.test.mjs — node:test coverage for slack/adapter.mjs
+ *
+ * Proves the re-homed translation is behaviour-preserving (round-trip through
+ * the writeInbox shim → MessageEvent → daemon eventToInboxItem reproduces the
+ * legacy socket-mode item) and that the enrich hook closes the 3 gaps
+ * (reaction kind, thread_context, channel_cc). Injects a fake socket client +
+ * fake fetch — no network, no real Slack.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { SlackAdapter, parseSlackConfig } from "./slack/adapter.mjs";
+import { eventToInboxItem as daemonEventToInboxItem } from "./inbox-item.mjs";
+import { eventToInboxItem as slackLegacyItem } from "../../scripts/poller/slack-socket-mode.mjs";
+
+async function makeRoot() {
+  const p = join(tmpdir(), `slack-adapter-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  await fsp.mkdir(p, { recursive: true });
+  return p;
+}
+async function rmRoot(p) { try { await fsp.rm(p, { recursive: true, force: true }); } catch { /* */ } }
+
+const IDS = { firstName: "Ravi", fullName: "Jamie Lee", slackMemberId: "UAGENT0001", principalSlackId: "UCEO000001" };
+
+/**
+ * A fake socket client capturing the opts the adapter passed (writeInbox,
+ * enrich, reactions, ccChannels) so the test can drive the seam directly.
+ */
+function fakeClientFactory(captured) {
+  return (opts) => {
+    captured.opts = opts;
+    return {
+      start: async () => { captured.started = true; },
+      stop: () => { captured.stopped = true; },
+      getStats: () => ({}),
+      getState: () => ({}),
+    };
+  };
+}
+
+function makeAdapter(root, extra = {}) {
+  const captured = {};
+  const a = new SlackAdapter({
+    agentRoot: root,
+    botToken: "xoxb-test",
+    appToken: "xapp-test",
+    createClient: fakeClientFactory(captured),
+    ...extra,
+  });
+  // Pre-seed identity/peers so _connect doesn't read config/agent.json.
+  a._identity = IDS;
+  a._peerSlackIds = new Set();
+  a._appToken = "xapp-test";
+  return { a, captured };
+}
+
+// ---------------------------------------------------------------------------
+// behaviour-preserving round-trip
+// ---------------------------------------------------------------------------
+
+test("writeInbox shim → MessageEvent → daemon item == legacy socket-mode item (DM)", async () => {
+  const root = await makeRoot();
+  try {
+    const { a, captured } = makeAdapter(root);
+    const received = [];
+    await a.start({ onInbound: (ev) => received.push(ev) });
+    assert.ok(captured.started, "adapter started the socket client");
+    assert.equal(captured.opts.reactions, true, "reactions on by default");
+
+    // Build the legacy item exactly as the socket client would, then feed it
+    // through the adapter's writeInbox shim (what the real client calls).
+    const envelope = {
+      payload: { event: { type: "message", user: "UHUMAN0001", text: "hey, draft the memo", ts: "1735689600.001000", channel: "DABCDEF01" } },
+    };
+    const legacy = slackLegacyItem(envelope, { ownSlackId: IDS.slackMemberId, principalSlackId: IDS.principalSlackId, agentFirstName: IDS.firstName });
+
+    captured.opts.writeInbox("slack", legacy);
+    assert.equal(received.length, 1, "event reached onInbound");
+    const ev = received[0];
+    assert.equal(ev.kind, "message");
+    assert.equal(ev.source.channel, "slack");
+    assert.equal(ev.source.chatId, "DABCDEF01");
+    assert.equal(ev.source.userScope, "dm");
+
+    // The daemon re-serializes the event — must reproduce the legacy item.
+    const reserialized = daemonEventToInboxItem(ev);
+    assert.deepEqual(reserialized, legacy, "round-trip must be byte-identical");
+  } finally { await rmRoot(root); }
+});
+
+test("Slack adapter uses pairingMode 'open' so DMs are never default-denied", async () => {
+  const root = await makeRoot();
+  try {
+    const { a, captured } = makeAdapter(root);
+    const received = [];
+    await a.start({ onInbound: (ev) => received.push(ev) });
+    // An un-allowlisted DM sender — pairing "open" must let it through.
+    const legacy = slackLegacyItem(
+      { payload: { event: { type: "message", user: "USTRANGER", text: "hi", ts: "1735689600.001000", channel: "DZZZ" } } },
+      { ownSlackId: IDS.slackMemberId, principalSlackId: IDS.principalSlackId, agentFirstName: IDS.firstName },
+    );
+    captured.opts.writeInbox("slack", legacy);
+    assert.equal(received.length, 1, "Slack DM must not be blocked by pairing (live-path preserved)");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// enrich hook — gap (b) thread_context, gap (a) reaction target text
+// ---------------------------------------------------------------------------
+
+test("enrich fills thread_context for a thread reply via conversations.replies", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeAdapter(root, {
+      fetchFn: async (url) => {
+        const u = String(url);
+        if (u.includes("conversations.replies")) {
+          return { json: async () => ({ ok: true, messages: [
+            { ts: "1735689500.000100", user: "UHUMAN0001", text: "original question" },
+            { ts: "1735689800.003000", user: "UHUMAN0001", text: "the reply itself" },
+          ] }) };
+        }
+        return { json: async () => ({ ok: false }) };
+      },
+    });
+    const envelope = { payload: { event: { type: "message", channel: "C1", ts: "1735689800.003000", thread_ts: "1735689500.000100", text: "the reply" } } };
+    const extra = await a._enrich(envelope);
+    assert.match(extra.threadContext, /original question/);
+    // The reply itself (>= beforeTs) is excluded from the prior context.
+    assert.doesNotMatch(extra.threadContext, /the reply itself/);
+  } finally { await rmRoot(root); }
+});
+
+test("enrich fills reaction target text via conversations.history", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeAdapter(root, {
+      fetchFn: async (url) => {
+        if (String(url).includes("conversations.history")) {
+          return { json: async () => ({ ok: true, messages: [{ ts: "1735689600.001000", text: "the message they reacted to" }] }) };
+        }
+        return { json: async () => ({ ok: false }) };
+      },
+    });
+    const envelope = { payload: { event: { type: "reaction_added", user: "UHUMAN0001", reaction: "eyes", item: { type: "message", channel: "C1", ts: "1735689600.001000" } } } };
+    const extra = await a._enrich(envelope);
+    assert.match(extra.threadContext, /reacted to/);
+  } finally { await rmRoot(root); }
+});
+
+test("enrich is fail-open: a fetch throw yields {} (event still flows)", async () => {
+  const root = await makeRoot();
+  try {
+    const { a } = makeAdapter(root, { fetchFn: async () => { throw new Error("slack 500"); } });
+    const envelope = { payload: { event: { type: "message", channel: "C1", ts: "2", thread_ts: "1", text: "x" } } };
+    const extra = await a._enrich(envelope);
+    assert.deepEqual(extra, {});
+  } finally { await rmRoot(root); }
+});
+
+test("enrich returns {} for a non-threaded message (no API call)", async () => {
+  const root = await makeRoot();
+  try {
+    let called = false;
+    const { a } = makeAdapter(root, { fetchFn: async () => { called = true; return { json: async () => ({ ok: true, messages: [] }) }; } });
+    const envelope = { payload: { event: { type: "message", channel: "C1", ts: "1735689600.001000", text: "top-level" } } };
+    const extra = await a._enrich(envelope);
+    assert.deepEqual(extra, {});
+    assert.equal(called, false, "top-level messages need no enrichment fetch");
+  } finally { await rmRoot(root); }
+});
+
+// ---------------------------------------------------------------------------
+// config parsing — cc_channels + reactions
+// ---------------------------------------------------------------------------
+
+test("parseSlackConfig reads ingest_mode, reactions, and cc_channels (list + inline)", () => {
+  const list = parseSlackConfig([
+    "ingest_mode: socket",
+    "reactions: on",
+    "cc_channels:",
+    "  - C0AAA   # eng",
+    '  - "C0BBB"',
+  ].join("\n"));
+  assert.equal(list.ingest_mode, "socket");
+  assert.equal(list.reactions, true);
+  assert.deepEqual(list.cc_channels, ["C0AAA", "C0BBB"]);
+
+  const inline = parseSlackConfig("cc_channels: [C1, \"C2\"]\nreactions: false\n");
+  assert.deepEqual(inline.cc_channels, ["C1", "C2"]);
+  assert.equal(inline.reactions, false);
+});
+
+test("cc_channels from config flow into the socket client opts", async () => {
+  const root = await makeRoot();
+  try {
+    await fsp.mkdir(join(root, "config"), { recursive: true });
+    await fsp.writeFile(join(root, "config/slack.yaml"), "ingest_mode: socket\nreactions: on\ncc_channels:\n  - C0WATCH\n");
+    const { a, captured } = makeAdapter(root, { slackConfig: undefined });
+    // slackConfig undefined → adapter loads config/slack.yaml itself.
+    const a2 = new SlackAdapter({ agentRoot: root, botToken: "x", createClient: () => ({ start: async () => {}, stop: () => {} }) });
+    assert.ok(a2._ccChannels.has("C0WATCH"));
+    assert.equal(a2._reactionsOn, true);
+    await a.start({ onInbound: () => {} });
+    void captured;
+  } finally { await rmRoot(root); }
+});