madarx 2.24.0 → 2.24.1

package/lib/channel-allowlist.js

@@ -0,0 +1,144 @@
+import { getDb, nowIso, newId } from './db.js';
+
+const KNOWN_CHANNELS = new Set(['whatsapp', 'telegram', 'slack', 'discord', 'imessage', 'signal', 'webhook']);
+
+export function normalizeChannel(channel) {
+  const value = String(channel || '').trim().toLowerCase();
+  if (!value) throw new Error('channel is required');
+  if (!KNOWN_CHANNELS.has(value)) throw new Error(`unsupported channel: ${value}`);
+  return value;
+}
+
+export function normalizeAddress(channel, value) {
+  const ch = normalizeChannel(channel);
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  if (ch === 'whatsapp') {
+    if (raw.includes('@')) return raw;
+    const digits = raw.replace(/[^0-9]/g, '');
+    return digits ? `${digits}@s.whatsapp.net` : '';
+  }
+  return raw;
+}
+
+export function inferAddressKind(channel, address) {
+  const ch = normalizeChannel(channel);
+  const value = String(address || '');
+  if (ch === 'whatsapp') return value.endsWith('@g.us') ? 'group' : 'dm';
+  if (ch === 'slack' || ch === 'discord') return value.startsWith('D') ? 'dm' : 'channel';
+  if (ch === 'telegram') return value.startsWith('-') ? 'group' : 'dm';
+  if (ch === 'webhook') return 'endpoint';
+  return 'dm';
+}
+
+function legacyWhatsAppRows() {
+  try {
+    return getDb().prepare(`
+      SELECT id, 'whatsapp' AS channel, chat_id AS address, chat_id, kind, label, created_at
+      FROM whatsapp_allowlist
+      ORDER BY created_at DESC
+    `).all();
+  } catch {
+    return [];
+  }
+}
+
+function genericRows(channel = null) {
+  const db = getDb();
+  if (channel) {
+    return db.prepare(`
+      SELECT id, channel, address, address AS chat_id, kind, label, created_at
+      FROM channel_allowlist
+      WHERE channel = ?
+      ORDER BY created_at DESC
+    `).all(normalizeChannel(channel));
+  }
+  return db.prepare(`
+    SELECT id, channel, address, address AS chat_id, kind, label, created_at
+    FROM channel_allowlist
+    ORDER BY channel ASC, created_at DESC
+  `).all();
+}
+
+export function listChannelAllowlist(channel = null) {
+  if (channel && normalizeChannel(channel) === 'whatsapp') {
+    const legacy = legacyWhatsAppRows();
+    const generic = genericRows('whatsapp');
+    const seen = new Set();
+    return [...legacy, ...generic].filter(row => {
+      const key = `${row.channel}:${row.address || row.chat_id}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+  if (channel) return genericRows(channel);
+  const legacy = legacyWhatsAppRows();
+  const generic = genericRows();
+  const seen = new Set();
+  return [...legacy, ...generic].filter(row => {
+    const key = `${row.channel}:${row.address || row.chat_id}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+export function isChannelAllowed(channel, address) {
+  const ch = normalizeChannel(channel);
+  const normalized = normalizeAddress(ch, address);
+  if (!normalized) return false;
+  if (ch === 'whatsapp') {
+    const legacy = getDb().prepare('SELECT id FROM whatsapp_allowlist WHERE chat_id = ? LIMIT 1').get(normalized);
+    if (legacy) return true;
+  }
+  return Boolean(getDb().prepare('SELECT id FROM channel_allowlist WHERE channel = ? AND address = ? LIMIT 1').get(ch, normalized));
+}
+
+export function addChannelAllowlistEntry({ channel, address, chat_id, kind = null, label = null }) {
+  const ch = normalizeChannel(channel);
+  const normalized = normalizeAddress(ch, address || chat_id);
+  if (!normalized) throw new Error('address is required');
+  const rowKind = kind || inferAddressKind(ch, normalized);
+  if (ch === 'whatsapp') {
+    const id = newId('waal');
+    getDb().prepare(`
+      INSERT INTO whatsapp_allowlist (id, chat_id, kind, label, created_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(chat_id) DO UPDATE SET kind = excluded.kind, label = excluded.label
+    `).run(id, normalized, String(rowKind), label ? String(label) : null, nowIso());
+    return getDb().prepare(`
+      SELECT id, 'whatsapp' AS channel, chat_id AS address, chat_id, kind, label, created_at
+      FROM whatsapp_allowlist WHERE chat_id = ?
+    `).get(normalized);
+  }
+  const id = newId('chal');
+  getDb().prepare(`
+    INSERT INTO channel_allowlist (id, channel, address, kind, label, created_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(channel, address) DO UPDATE SET kind = excluded.kind, label = excluded.label
+  `).run(id, ch, normalized, String(rowKind), label ? String(label) : null, nowIso());
+  return getDb().prepare(`
+    SELECT id, channel, address, address AS chat_id, kind, label, created_at
+    FROM channel_allowlist WHERE channel = ? AND address = ?
+  `).get(ch, normalized);
+}
+
+export function removeChannelAllowlistEntry(channel, address) {
+  const ch = normalizeChannel(channel);
+  const normalized = normalizeAddress(ch, address);
+  if (!normalized) return 0;
+  if (ch === 'whatsapp') {
+    const legacy = getDb().prepare('DELETE FROM whatsapp_allowlist WHERE chat_id = ?').run(normalized).changes;
+    const generic = getDb().prepare('DELETE FROM channel_allowlist WHERE channel = ? AND address = ?').run(ch, normalized).changes;
+    return legacy + generic;
+  }
+  return getDb().prepare('DELETE FROM channel_allowlist WHERE channel = ? AND address = ?').run(ch, normalized).changes;
+}
+
+export function channelAllowlistSummary() {
+  const rows = listChannelAllowlist();
+  const counts = Object.fromEntries([...KNOWN_CHANNELS].map(channel => [channel, 0]));
+  for (const row of rows) counts[row.channel] = (counts[row.channel] || 0) + 1;
+  return counts;
+}

package/lib/channels/discord-adapter.js

@@ -0,0 +1,117 @@
+// @ts-check
+/**
+ * R2 — Discord channel adapter.
+ *
+ * Transport-only wrapper over the Discord REST API (v10). It normalizes inbound
+ * gateway message objects to the canonical {@link ChannelEvent} — including
+ * attachment → media mapping — and sends replies through the channel-messages
+ * endpoint. No routing / allowlist / rate-limit logic lives here. Token and
+ * `fetch` resolve lazily at send time: inject `{ token, fetch }` in tests;
+ * otherwise `DISCORD_BOT_TOKEN` + global `fetch` are used. The bot auth scheme is
+ * `Bot <token>`. Inbound is gateway/webhook-driven, so `connect`/`disconnect` are
+ * no-ops.
+ */
+
+import { defineAdapter, normalizeInbound } from './contract.js';
+
+/** @typedef {import('./contract.js').ChannelEvent} ChannelEvent */
+/** @typedef {import('./contract.js').ChannelMedia} ChannelMedia */
+
+/**
+ * @typedef {Object} DiscordAdapterConfig
+ * @property {string} [token]   - bot token; falls back to DISCORD_BOT_TOKEN at send time
+ * @property {typeof fetch} [fetch] - fetch impl; falls back to global fetch at send time
+ */
+
+/**
+ * Map a Discord attachment content-type to a canonical media type.
+ * @param {string|undefined} contentType
+ * @returns {string}
+ */
+function mediaTypeFromMime(contentType) {
+  if (typeof contentType !== 'string') return 'document';
+  if (contentType.startsWith('image/')) return 'image';
+  if (contentType.startsWith('video/')) return 'video';
+  if (contentType.startsWith('audio/')) return 'audio';
+  return 'document';
+}
+
+/**
+ * Map a Discord attachment object to a {@link ChannelMedia} entry. Only present
+ * fields are included so the shape stays minimal.
+ * @param {Record<string, *>} att
+ * @returns {ChannelMedia}
+ */
+function mapAttachment(att) {
+  /** @type {ChannelMedia} */
+  const media = { type: mediaTypeFromMime(att?.content_type), url: att?.url };
+  if (att?.content_type) media.mimetype = att.content_type;
+  if (att?.filename) media.filename = att.filename;
+  return media;
+}
+
+/**
+ * Normalize a Discord gateway message object into a {@link ChannelEvent}.
+ * The original payload is preserved by reference.
+ * @param {Record<string, *>} raw
+ * @returns {ChannelEvent}
+ */
+export function normalizeDiscord(raw) {
+  const src = raw && typeof raw === 'object' ? raw : {};
+  const author = src.author || {};
+  const attachments = Array.isArray(src.attachments) ? src.attachments : [];
+  const mapped = {
+    chat_id: src.channel_id,
+    sender: author.id,
+    message_id: src.id,
+    text: src.content,
+    ts: src.timestamp,
+    media: attachments.map(mapAttachment),
+  };
+  const event = normalizeInbound('discord', mapped);
+  event.raw = raw;
+  return event;
+}
+
+/**
+ * Create a transport-only Discord adapter.
+ * @param {DiscordAdapterConfig} [config]
+ * @returns {import('./contract.js').ChannelAdapter}
+ */
+export function createDiscordAdapter(config = {}) {
+  const resolveToken = () => {
+    const token = config.token || process.env.DISCORD_BOT_TOKEN;
+    if (!token) throw new Error('discord adapter: no bot token (set DISCORD_BOT_TOKEN or inject { token })');
+    return token;
+  };
+  const resolveFetch = () => {
+    const f = config.fetch || globalThis.fetch;
+    if (typeof f !== 'function') throw new Error('discord adapter: no fetch available (inject { fetch })');
+    return f;
+  };
+
+  return defineAdapter({
+    channel: 'discord',
+    async connect() { return { ok: true, mode: 'gateway' }; },
+    async disconnect() { return { ok: true }; },
+    /**
+     * @param {string} chatId
+     * @param {string} text
+     */
+    async send(chatId, text) {
+      const token = resolveToken();
+      const res = await resolveFetch()(`https://discord.com/api/v10/channels/${chatId}/messages`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bot ${token}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ content: text }),
+      });
+      const data = /** @type {*} */ (await res.json());
+      const id = data?.id;
+      return { ok: true, message_id: id != null ? String(id) : null, raw: data };
+    },
+    normalizeInbound: normalizeDiscord,
+  });
+}

package/lib/channels/imessage-adapter.js

@@ -0,0 +1,106 @@
+// @ts-check
+/**
+ * R2 — iMessage channel adapter.
+ *
+ * Transport-only wrapper over the local macOS Messages app. It normalizes simple
+ * local Messages event fields to the canonical {@link ChannelEvent} and sends
+ * replies by driving `osascript` (AppleScript) at send time. No routing /
+ * allowlist / rate-limit logic lives here. The command runner resolves lazily at
+ * send time: inject `{ run }` in tests; otherwise `child_process.execFile` runs
+ * `osascript` locally. There are no network credentials — delivery is local to the
+ * machine's signed-in Messages account, so `connect`/`disconnect` are no-ops.
+ */
+
+import { defineAdapter, normalizeInbound } from './contract.js';
+
+/** @typedef {import('./contract.js').ChannelEvent} ChannelEvent */
+
+/**
+ * @typedef {Object} IMessageAdapterConfig
+ * @property {(command: string, args: string[]) => Promise<*>} [run] - command runner; falls back to execFile(osascript) at send time
+ */
+
+/**
+ * Normalize a local Messages event into a {@link ChannelEvent}. The simple local
+ * shape already uses canonical field names (`chat_id`, `sender`, `message_id`,
+ * `text`, `timestamp`), so this defers to {@link normalizeInbound}. The original
+ * payload is preserved by reference.
+ * @param {Record<string, *>} raw
+ * @returns {ChannelEvent}
+ */
+export function normalizeIMessage(raw) {
+  const event = normalizeInbound('imessage', raw);
+  event.raw = raw;
+  return event;
+}
+
+/**
+ * Escape a string for safe interpolation into an AppleScript string literal.
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeAppleScript(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Build the `osascript` argument vector that sends `text` to `chatId` (a phone
+ * number or email handle) through the signed-in iMessage account.
+ * @param {string} chatId
+ * @param {string} text
+ * @returns {string[]}
+ */
+function buildOsascriptArgs(chatId, text) {
+  const lines = [
+    'tell application "Messages"',
+    `set targetBuddy to "${escapeAppleScript(chatId)}"`,
+    'set targetService to id of 1st account whose service type = iMessage',
+    `send "${escapeAppleScript(text)}" to buddy targetBuddy of service id targetService`,
+    'end tell',
+  ];
+  return lines.flatMap((line) => ['-e', line]);
+}
+
+/**
+ * Run a command via `child_process.execFile`, resolving with `{ stdout, stderr }`.
+ * Imported lazily so the module loads without `node:child_process` in environments
+ * that only ever inject a `run`.
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+async function execFileRun(command, args) {
+  const { execFile } = await import('node:child_process');
+  return new Promise((resolve, reject) => {
+    execFile(command, args, (err, stdout, stderr) => {
+      if (err) reject(err);
+      else resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
+/**
+ * Create a transport-only iMessage adapter.
+ * @param {IMessageAdapterConfig} [config]
+ * @returns {import('./contract.js').ChannelAdapter}
+ */
+export function createIMessageAdapter(config = {}) {
+  const run = typeof config.run === 'function' ? config.run : execFileRun;
+
+  return defineAdapter({
+    channel: 'imessage',
+    // Local delivery; nothing persistent to open or close.
+    async connect() { return { ok: true, mode: 'local' }; },
+    async disconnect() { return { ok: true }; },
+    /**
+     * @param {string} chatId
+     * @param {string} text
+     */
+    async send(chatId, text) {
+      const args = buildOsascriptArgs(String(chatId), text);
+      const result = await run('osascript', args);
+      return { ok: true, message_id: null, raw: result };
+    },
+    normalizeInbound: normalizeIMessage,
+  });
+}

package/lib/channels/index.js

@@ -10,8 +10,8 @@
  * …and the generic router can route + reply through it with no core change.
  *
  * Status: foundation shipped (contract, registry, deterministic routing, generic
- * router, WhatsApp adapter seam). Telegram / Slack / Discord / iMessage / Signal
- * are follow-on adapters — not yet implemented.
+ * router) plus the R2 acceptance channels: WhatsApp / Telegram / Slack / Discord /
+ * iMessage / Signal / Webhook adapters.
  */
 
 export { normalizeInbound, defineAdapter } from './contract.js';
@@ -19,16 +19,53 @@ export { createRegistry, defaultRegistry } from './registry.js';
 export { resolveRoute, routeSpecificity, bindingMatches, originOf } from './routing.js';
 export { dispatchInbound, sendReply } from './router.js';
 export { whatsappAdapter, normalizeWhatsApp } from './whatsapp-adapter.js';
+export { createTelegramAdapter, normalizeTelegram } from './telegram-adapter.js';
+export { createSlackAdapter, normalizeSlack } from './slack-adapter.js';
+export { createDiscordAdapter, normalizeDiscord } from './discord-adapter.js';
+export { createIMessageAdapter, normalizeIMessage } from './imessage-adapter.js';
+export { createSignalAdapter, normalizeSignal } from './signal-adapter.js';
+export { createWebhookAdapter, normalizeWebhook } from './webhook-adapter.js';
 
 import { defaultRegistry } from './registry.js';
 import { whatsappAdapter } from './whatsapp-adapter.js';
+import { createTelegramAdapter } from './telegram-adapter.js';
+import { createSlackAdapter } from './slack-adapter.js';
+import { createDiscordAdapter } from './discord-adapter.js';
+import { createIMessageAdapter } from './imessage-adapter.js';
+import { createSignalAdapter } from './signal-adapter.js';
+import { createWebhookAdapter } from './webhook-adapter.js';
+
+/**
+ * Per-adapter construction config for {@link registerBuiltinAdapters}. Each entry
+ * accepts injected dependencies (used by tests and explicit wiring); anything
+ * omitted resolves from env vars / global fetch / the local runner at send time.
+ * @typedef {Object} BuiltinAdapterConfig
+ * @property {import('./telegram-adapter.js').TelegramAdapterConfig} [telegram]
+ * @property {import('./slack-adapter.js').SlackAdapterConfig} [slack]
+ * @property {import('./discord-adapter.js').DiscordAdapterConfig} [discord]
+ * @property {import('./imessage-adapter.js').IMessageAdapterConfig} [imessage]
+ * @property {import('./signal-adapter.js').SignalAdapterConfig} [signal]
+ * @property {import('./webhook-adapter.js').WebhookAdapterConfig} [webhook]
+ */
 
 /**
  * Register the built-in adapters into a registry (default: the shared one).
  * Idempotent — safe to call at every boot. Follow-on channels register here too.
+ *
+ * All R2 acceptance adapters are always registered. Environment- or device-backed
+ * transports resolve their credentials / local CLIs lazily at send time, so a bare
+ * `registerBuiltinAdapters()` is still safe in tests and boot paths that do not
+ * exercise those sends.
  * @param {import('./registry.js').ChannelRegistry} [registry]
+ * @param {BuiltinAdapterConfig} [config] - optional per-adapter dependency injection
  */
-export function registerBuiltinAdapters(registry = defaultRegistry) {
+export function registerBuiltinAdapters(registry = defaultRegistry, config = {}) {
   registry.register(whatsappAdapter, { replace: true });
+  registry.register(createTelegramAdapter(config.telegram), { replace: true });
+  registry.register(createSlackAdapter(config.slack), { replace: true });
+  registry.register(createDiscordAdapter(config.discord), { replace: true });
+  registry.register(createIMessageAdapter(config.imessage), { replace: true });
+  registry.register(createSignalAdapter(config.signal), { replace: true });
+  registry.register(createWebhookAdapter(config.webhook), { replace: true });
   return registry;
 }

package/lib/channels/signal-adapter.js

@@ -0,0 +1,96 @@
+// @ts-check
+/**
+ * R2 — Signal channel adapter.
+ *
+ * Transport-only wrapper over `signal-cli`. It normalizes inbound signal-cli JSON
+ * envelopes to the canonical {@link ChannelEvent} and sends replies by invoking
+ * `signal-cli` at send time. No routing / allowlist / rate-limit logic lives here.
+ * The command runner resolves lazily at send time: inject `{ run }` in tests;
+ * otherwise `child_process.execFile` runs `signal-cli` locally. The account is
+ * resolved at send time from `config.account` or `SIGNAL_CLI_ACCOUNT`. Inbound is
+ * poller/daemon-driven, so `connect`/`disconnect` are no-ops.
+ */
+
+import { defineAdapter, normalizeInbound } from './contract.js';
+
+/** @typedef {import('./contract.js').ChannelEvent} ChannelEvent */
+
+/**
+ * @typedef {Object} SignalAdapterConfig
+ * @property {string} [account] - sender account; falls back to SIGNAL_CLI_ACCOUNT at send time
+ * @property {(command: string, args: string[]) => Promise<*>} [run] - command runner; falls back to execFile(signal-cli) at send time
+ */
+
+/**
+ * Normalize a signal-cli JSON envelope into a {@link ChannelEvent}. Accepts a full
+ * `{ envelope: {...} }` wrapper, a bare envelope, or an already-normalized event.
+ * The original payload is preserved by reference.
+ * @param {Record<string, *>} raw
+ * @returns {ChannelEvent}
+ */
+export function normalizeSignal(raw) {
+  const src = raw && typeof raw === 'object' ? raw : {};
+  const env = src.envelope || src;
+  const data = env?.dataMessage || {};
+  const timestamp = env?.timestamp;
+  const mapped = {
+    chat_id: env?.source,
+    sender: env?.source,
+    message_id: timestamp,
+    text: data?.message,
+    ts: timestamp != null ? new Date(Number(timestamp)).toISOString() : undefined,
+  };
+  const event = normalizeInbound('signal', mapped);
+  event.raw = raw;
+  return event;
+}
+
+/**
+ * Run a command via `child_process.execFile`, resolving with `{ stdout, stderr }`.
+ * Imported lazily so the module loads without `node:child_process` in environments
+ * that only ever inject a `run`.
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+async function execFileRun(command, args) {
+  const { execFile } = await import('node:child_process');
+  return new Promise((resolve, reject) => {
+    execFile(command, args, (err, stdout, stderr) => {
+      if (err) reject(err);
+      else resolve({ stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
+/**
+ * Create a transport-only Signal adapter.
+ * @param {SignalAdapterConfig} [config]
+ * @returns {import('./contract.js').ChannelAdapter}
+ */
+export function createSignalAdapter(config = {}) {
+  const run = typeof config.run === 'function' ? config.run : execFileRun;
+  const resolveAccount = () => {
+    const account = config.account || process.env.SIGNAL_CLI_ACCOUNT;
+    if (!account) throw new Error('signal adapter: no account (set SIGNAL_CLI_ACCOUNT or inject { account })');
+    return account;
+  };
+
+  return defineAdapter({
+    channel: 'signal',
+    // Poller/daemon-driven; nothing persistent to open or close.
+    async connect() { return { ok: true, mode: 'cli' }; },
+    async disconnect() { return { ok: true }; },
+    /**
+     * @param {string} chatId
+     * @param {string} text
+     */
+    async send(chatId, text) {
+      const account = resolveAccount();
+      const args = ['-a', account, 'send', '-m', text, String(chatId)];
+      const result = await run('signal-cli', args);
+      return { ok: true, message_id: null, raw: result };
+    },
+    normalizeInbound: normalizeSignal,
+  });
+}

package/lib/channels/slack-adapter.js

@@ -0,0 +1,86 @@
+// @ts-check
+/**
+ * R2 — Slack channel adapter.
+ *
+ * Transport-only wrapper over the Slack Web API. It normalizes inbound Events API
+ * envelopes to the canonical {@link ChannelEvent} and sends replies through
+ * `chat.postMessage`. No routing / allowlist / rate-limit logic lives here. Token
+ * and `fetch` resolve lazily at send time: inject `{ token, fetch }` in tests;
+ * otherwise `SLACK_BOT_TOKEN` + global `fetch` are used. Inbound is event-driven,
+ * so `connect`/`disconnect` are no-ops.
+ */
+
+import { defineAdapter, normalizeInbound } from './contract.js';
+
+/** @typedef {import('./contract.js').ChannelEvent} ChannelEvent */
+
+/**
+ * @typedef {Object} SlackAdapterConfig
+ * @property {string} [token]   - bot token; falls back to SLACK_BOT_TOKEN at send time
+ * @property {typeof fetch} [fetch] - fetch impl; falls back to global fetch at send time
+ */
+
+/**
+ * Normalize a Slack Events API payload into a {@link ChannelEvent}.
+ * Accepts a full envelope (`{ event: {...} }`), a bare event, or an
+ * already-normalized event. The original payload is preserved by reference.
+ * @param {Record<string, *>} raw
+ * @returns {ChannelEvent}
+ */
+export function normalizeSlack(raw) {
+  const src = raw && typeof raw === 'object' ? raw : {};
+  const ev = src.event || src;
+  const mapped = {
+    chat_id: ev?.channel,
+    sender: ev?.user || ev?.bot_id,
+    message_id: ev?.ts,
+    text: ev?.text,
+    ts: ev?.ts,
+  };
+  const event = normalizeInbound('slack', mapped);
+  event.raw = raw;
+  return event;
+}
+
+/**
+ * Create a transport-only Slack adapter.
+ * @param {SlackAdapterConfig} [config]
+ * @returns {import('./contract.js').ChannelAdapter}
+ */
+export function createSlackAdapter(config = {}) {
+  const resolveToken = () => {
+    const token = config.token || process.env.SLACK_BOT_TOKEN;
+    if (!token) throw new Error('slack adapter: no bot token (set SLACK_BOT_TOKEN or inject { token })');
+    return token;
+  };
+  const resolveFetch = () => {
+    const f = config.fetch || globalThis.fetch;
+    if (typeof f !== 'function') throw new Error('slack adapter: no fetch available (inject { fetch })');
+    return f;
+  };
+
+  return defineAdapter({
+    channel: 'slack',
+    async connect() { return { ok: true, mode: 'events_api' }; },
+    async disconnect() { return { ok: true }; },
+    /**
+     * @param {string} chatId
+     * @param {string} text
+     */
+    async send(chatId, text) {
+      const token = resolveToken();
+      const res = await resolveFetch()('https://slack.com/api/chat.postMessage', {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify({ channel: String(chatId), text }),
+      });
+      const data = /** @type {*} */ (await res.json());
+      const id = data?.ts;
+      return { ok: data?.ok !== false, message_id: id != null ? String(id) : null, raw: data };
+    },
+    normalizeInbound: normalizeSlack,
+  });
+}

package/lib/channels/smoke.js

@@ -0,0 +1,36 @@
+import { createRegistry } from './registry.js';
+import { registerBuiltinAdapters } from './index.js';
+import { getConnectivityStatus } from '../connectivity-status.js';
+
+const SMOKE_TEXT = 'madarX OS V-REACH smoke test';
+
+export async function runChannelSmoke({ channel, address, text = SMOKE_TEXT, adapterConfig = {}, dryRun = true } = {}) {
+  if (!channel) throw new Error('channel is required');
+  const registry = registerBuiltinAdapters(createRegistry(), adapterConfig);
+  const adapter = registry.get(String(channel));
+  if (!adapter) throw new Error(`unsupported channel: ${channel}`);
+  if (!address) {
+    return { channel: String(channel), ok: false, skipped: 'missing_address' };
+  }
+  if (dryRun) {
+    return { channel: String(channel), ok: true, dry_run: true, address: String(address), text };
+  }
+  const result = await adapter.send(String(address), text);
+  return { channel: String(channel), ok: true, dry_run: false, result };
+}
+
+export async function getVReachSmokeMatrix({ includeHealth = false } = {}) {
+  const status = await getConnectivityStatus({ includeHealth });
+  return {
+    ok: true,
+    metric: 'V-REACH',
+    target: '>=6 configured, allowlisted channels behind deterministic adapters',
+    channels: status.channels.map(row => ({
+      channel: row.channel,
+      configured: row.configured,
+      allowlist_count: row.allowlist_count,
+      ready_for_live_smoke: row.ready_for_live_smoke,
+      missing: row.missing,
+    })),
+  };
+}