@cohortapp/agent-sdk 2.3.0

package/lib/channels/base-adapter.mjs

@@ -0,0 +1,719 @@
+/**
+ * Maestro — BaseAdapter (cross-cutting channel logic)
+ *
+ * WS2 (design §5) factors the logic every real-time channel shares into one
+ * base class so concrete adapters implement only the platform-specific hooks:
+ *
+ *   abstract _connect({ onRaw, signal })  open the live stream; call onRaw(raw)
+ *                                         per provider frame.
+ *   abstract _toEvent(raw) → MessageEvent|null  translate a raw frame to a
+ *                                         contract MessageEvent (null to drop).
+ *   abstract _send(out) → SendResult      send an outbound message.
+ *   optional  _react(out) → SendResult    add/remove a reaction.
+ *   optional  _setTyping(source, on)      set/clear a typing indicator.
+ *
+ * BaseAdapter provides:
+ *   - `start({ onInbound, signal })` — wires _connect → _toEvent → (pairing
+ *     gate) → onInbound, stamping `ev.channel`. The pairing gate runs in the
+ *     onInbound wrapper so every channel inherits default-deny DMs + pair-code
+ *     interception (lib/channels/pairing.mjs). Pairing/gate failures are
+ *     fail-open-logged, never thrown into the live loop.
+ *   - `send(out)` — thin wrapper over `_send` with uniform error shaping.
+ *   - `startTypingHeartbeat(source)` / `stopTypingHeartbeat(source)` — a
+ *     ~4s setInterval that calls `_setTyping(source, true)`, timeout-guarded so
+ *     a hung provider call can't wedge the loop. The dispatcher starts the
+ *     heartbeat on session spawn and stops it on session close.
+ *   - `react(out)`, `setTyping(...)`, `stop()`, `healthCheck()`.
+ *
+ * The base is transport-agnostic and hermetic: it never imports a provider SDK.
+ * Concrete adapters are dynamic-import-gated (like baileys/grammy).
+ *
+ * @module lib/channels/base-adapter
+ */
+
+"use strict";
+
+import { resolve } from "node:path";
+import { checkAllowed, startPairing, redeemPairing } from "./pairing.mjs";
+import { screenOutbound as defaultScreenOutbound } from "../comms/send-gate.mjs";
+import { getHookBus } from "../hooks/bus.mjs";
+import { superviseConnection as defaultSupervise, CONN_STATE } from "../util/reconnect.mjs";
+import { bump as defaultBump } from "../diagnostics/counters.mjs";
+
+const DEFAULT_TYPING_INTERVAL_MS = 4_000;
+const DEFAULT_TYPING_CALL_TIMEOUT_MS = 3_000;
+
+/* ───────────────────── bot-loop / reply-storm guard knobs ─────────────────── */
+// Two agents sharing one channel can ping-pong forever ("ok" → "ok" → …). The
+// pair guard is a per-conversation sliding window: if more than
+// PAIR_GUARD_MAX outbound replies land inside PAIR_GUARD_WINDOW_MS for the same
+// conversation, further sends are suppressed until the window drains. This is a
+// last-ditch circuit breaker BELOW the ownership filter (which already drops a
+// known peer-agent inbound) — it catches the storm even when the other party
+// isn't a *registered* peer agent. Cheap, in-memory, fail-open.
+const PAIR_GUARD_WINDOW_MS = 60_000;
+const PAIR_GUARD_MAX = 6;
+
+/** Diagnostic counter names (gaps-product-quality P0-6: count every fail-open). */
+export const CHANNEL_COUNTERS = Object.freeze({
+  SEND_GATE_BLOCKED: "channel.send_gate.blocked",
+  SEND_GATE_FAILOPEN: "channel.send_gate.fail_open",
+  PAIR_GUARD_TRIPPED: "channel.pair_guard.tripped",
+  PEER_AGENT_DROPPED: "channel.peer_agent.dropped",
+  RECONNECT_DOWN: "channel.reconnect.down",
+  RECONNECT_GAVE_UP: "channel.reconnect.gave_up",
+  RECONNECT_RECOVERED: "channel.reconnect.recovered",
+});
+
+export class BaseAdapter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.name            channel name (e.g. "telegram")
+   * @param {string} [opts.agentRoot]
+   * @param {string[]} [opts.capabilities]
+   * @param {object} [opts.config]        loaded config/<name>.yaml
+   * @param {(lvl:string,msg:string)=>void} [opts.log]
+   * @param {string} [opts.ownId]         the agent's own peer id on this channel
+   * @param {Set<string>|string[]} [opts.peerAgentIds]
+   * @param {number} [opts.typingIntervalMs]
+   * @param {(source:object)=>Promise<void>|void} [opts.onPairingPrompt]  one-time
+   *        reply to an unknown DM sender (e.g. "DM me `pair <code>`"). Optional.
+   * @param {"deny"|"open"} [opts.pairingMode="deny"]  "deny" = default-deny
+   *        unknown DM senders (new channels: Telegram/WhatsApp). "open" = skip
+   *        the pairing gate entirely because channel membership/identity is
+   *        already governed upstream (Slack: shouldKeepEvent + directed-gate).
+   *        Behaviour-preserving for the live Slack path.
+   * @param {boolean} [opts.sendGate=true]  run the shared outbound send-gate
+   *        (lib/comms/send-gate + hook-bus beforeSend) before every _send. Set
+   *        false only for a path already gated upstream.
+   * @param {boolean} [opts.supervise=true]  wrap _connect in the bounded-backoff
+   *        reconnect supervisor (lib/util/reconnect) so a dropped channel
+   *        reconnects and a dead channel turns healthCheck() red.
+   * @param {object} [opts.screenOutbound]  inject the send-gate fn (tests).
+   * @param {object} [opts.hookBus]  inject a HookBus (tests); default = the
+   *        process-wide singleton getHookBus().
+   * @param {Function} [opts.superviseConnection]  inject the reconnect supervisor.
+   * @param {Function} [opts.bump]  inject the diagnostics counter (tests).
+   * @param {string} [opts.jurisdiction]  recipient jurisdiction for disclosure.
+   * @param {string[]} [opts.internalDomains]  email domains treated as internal.
+   * @param {() => number} [opts.rng]  jitter RNG for the reconnect supervisor.
+   */
+  constructor(opts = {}) {
+    this.name = opts.name || "channel";
+    this.agentRoot = resolve(opts.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd());
+    this.capabilities = Array.isArray(opts.capabilities) ? opts.capabilities.slice() : [];
+    this.config = opts.config || {};
+    this.log = opts.log || ((lvl, m) => process.stdout.write(`[${this.name}:${lvl}] ${m}\n`));
+    this.ownId = opts.ownId || "";
+    this.peerAgentIds = toPeerSet(opts.peerAgentIds);
+    this.onPairingPrompt = typeof opts.onPairingPrompt === "function" ? opts.onPairingPrompt : null;
+    this.pairingMode = opts.pairingMode === "open" ? "open" : "deny";
+
+    this._typingIntervalMs = opts.typingIntervalMs || DEFAULT_TYPING_INTERVAL_MS;
+    this._setTimeout = opts.setTimeout || globalThis.setTimeout;
+    this._clearTimeout = opts.clearTimeout || globalThis.clearTimeout;
+    this._setInterval = opts.setInterval || globalThis.setInterval;
+    this._clearInterval = opts.clearInterval || globalThis.clearInterval;
+
+    // -- outbound governance (P0-3): the shared send-gate runs before _send. --
+    this._sendGateEnabled = opts.sendGate !== false;
+    this._screenOutbound =
+      typeof opts.screenOutbound === "function" ? opts.screenOutbound : defaultScreenOutbound;
+    this._hookBus = opts.hookBus || null; // resolved lazily so the singleton is shared
+    this._jurisdiction = opts.jurisdiction || undefined;
+    this._internalDomains = Array.isArray(opts.internalDomains) ? opts.internalDomains.slice() : [];
+
+    // -- reconnect supervision (P0-5/P0-6). --
+    this._superviseEnabled = opts.supervise !== false;
+    this._superviseConnection =
+      typeof opts.superviseConnection === "function" ? opts.superviseConnection : defaultSupervise;
+    // Health-poll interval for the reconnect supervisor: without it the poll is
+    // off and a SILENT drop (transport unhealthy but _connect never rejected)
+    // goes undetected. Default 30s; 0 disables (tests/adapters with push-based
+    // drop signalling via notifyDown).
+    this._healthIntervalMs = Number.isFinite(opts.healthIntervalMs) ? opts.healthIntervalMs : 30_000;
+    this._supervisor = null;
+    this._connState = CONN_STATE.CONNECTING;
+    this._rng = typeof opts.rng === "function" ? opts.rng : undefined;
+
+    // -- diagnostics counter (P0-6): every fail-open is counted somewhere. --
+    this._bump = typeof opts.bump === "function" ? opts.bump : defaultBump;
+
+    this._onInbound = null;
+    this._signal = null;
+    this._stopping = false;
+    /** @type {Map<string, any>} sessionKey → interval handle */
+    this._typingTimers = new Map();
+    // De-dupe one-time pairing prompts per unknown sender so we don't spam.
+    this._promptedPeers = new Set();
+    // Sliding-window reply timestamps per conversation key (bot-loop guard).
+    /** @type {Map<string, number[]>} */
+    this._replyWindow = new Map();
+  }
+
+  /** Resolve the HookBus (the shared singleton unless one was injected). */
+  _bus() {
+    if (this._hookBus) return this._hookBus;
+    try {
+      this._hookBus = getHookBus();
+    } catch {
+      this._hookBus = null; // never let bus construction wedge a send
+    }
+    return this._hookBus;
+  }
+
+  /** Count a guard event without ever throwing into the observed path. */
+  _count(name, attrs) {
+    try {
+      this._bump(name, { channel: this.name, ...(attrs || {}) }, { agentRoot: this.agentRoot });
+    } catch {
+      /* a counter must never crash the path it observes */
+    }
+  }
+
+  // -- Abstract hooks (subclasses must override _connect/_toEvent/_send) -----
+
+  /* eslint-disable no-unused-vars */
+  async _connect({ onRaw, signal }) {
+    throw new Error(`${this.name}: _connect() not implemented`);
+  }
+  _toEvent(raw) {
+    throw new Error(`${this.name}: _toEvent() not implemented`);
+  }
+  async _send(out) {
+    throw new Error(`${this.name}: _send() not implemented`);
+  }
+  async _react(out) {
+    // Optional — default no-op for channels without reactions.
+    return { ok: false, error: "react-not-supported" };
+  }
+  async _setTyping(source, on) {
+    // Optional — default no-op for channels without typing (SMS/Gmail).
+  }
+  /* eslint-enable no-unused-vars */
+
+  // -- start: connect → translate → gate → onInbound ------------------------
+
+  /**
+   * @param {object} args
+   * @param {(item:object)=>void} args.onInbound  called per accepted MessageEvent
+   * @param {AbortSignal} [args.signal]
+   */
+  async start({ onInbound, signal }) {
+    if (typeof onInbound !== "function") throw new Error(`${this.name} start(): onInbound required`);
+    this._onInbound = onInbound;
+    this._signal = signal || null;
+    this._stopping = false;
+    if (signal) signal.addEventListener?.("abort", () => { this._stopping = true; });
+
+    const onRaw = (raw) => {
+      // Translation + gating must never throw into the provider's frame loop.
+      let ev;
+      try {
+        ev = this._toEvent(raw);
+      } catch (err) {
+        this.log("error", `_toEvent threw: ${err.message}`);
+        return;
+      }
+      if (!ev) return; // adapter chose to drop this frame
+      if (!ev.channel) ev.channel = this.name;
+      this._handleEvent(ev);
+    };
+
+    // P0-5/P0-6: a live channel that drops must reconnect (bounded backoff) and
+    // a dead one must turn healthCheck() red — today nothing supervises this.
+    // The supervisor owns the connect loop: each (re)connect attempt calls
+    // _connect, and every state transition is surfaced + counted so the channel
+    // can never silently die. We still AWAIT the first connect so callers that
+    // act immediately after start() (e.g. driving onRaw) see a live adapter.
+    if (this._superviseEnabled && typeof this._superviseConnection === "function") {
+      this._supervisor = this._superviseConnection({
+        connect: () => this._connect({ onRaw, signal }),
+        isHealthy: () => this._connectionHealthy(),
+        onState: (state, info) => this._onConnState(state, info),
+        healthIntervalMs: this._healthIntervalMs,
+        setTimeout: this._setTimeout,
+        clearTimeout: this._clearTimeout,
+        rng: this._rng,
+      });
+      if (signal) {
+        signal.addEventListener?.("abort", () => {
+          try { this._supervisor?.stop?.("aborted"); } catch { /* */ }
+        });
+      }
+      try {
+        await this._supervisor.started; // first connect attempt
+      } catch {
+        /* a failed first connect is handled by the supervisor's backoff loop */
+      }
+      return;
+    }
+
+    // Unsupervised path (supervise:false): connect once, no reconnect.
+    await this._connect({ onRaw, signal });
+  }
+
+  /**
+   * Per-adapter liveness probe the reconnect supervisor polls (and the daemon
+   * health sweep can reuse via healthCheck). Default: live unless the supervisor
+   * has reported the connection down/giving-up. Adapters with a cheap socket
+   * probe can override. Never throws — a thrown probe is an unhealthy probe.
+   * @returns {Promise<boolean>|boolean}
+   */
+  _connectionHealthy() {
+    return this._connState === CONN_STATE.UP || this._connState === CONN_STATE.CONNECTING;
+  }
+
+  /**
+   * Reconnect-supervisor state sink. Records the current state (so healthCheck
+   * reflects it) and counts every transition so a drop/giving-up is never
+   * silent (P0-6). Fail-open: a throwing counter can't break the supervisor.
+   */
+  _onConnState(state, info = {}) {
+    this._connState = state;
+    if (state === CONN_STATE.UP) {
+      // A reconnection (reconnected:true) is the noteworthy recovery; the very
+      // first connect (reconnected:false) is just normal startup.
+      if (info.reconnected) {
+        this._count(CHANNEL_COUNTERS.RECONNECT_RECOVERED, { attempt: info.attempt });
+        this.log("info", `${this.name}: reconnected after a drop`);
+      }
+    } else if (state === CONN_STATE.DOWN) {
+      this._count(CHANNEL_COUNTERS.RECONNECT_DOWN, { reason: info.reason, delayMs: info.delayMs });
+      this.log("warn", `${this.name}: connection down (${info.reason || "?"}) — retrying in ${info.delayMs ?? "?"}ms`);
+    } else if (state === CONN_STATE.GIVING_UP) {
+      this._count(CHANNEL_COUNTERS.RECONNECT_GAVE_UP, { attempts: info.attempts, reason: info.reason });
+      this.log("error", `${this.name}: gave up reconnecting after ${info.attempts ?? "?"} attempts — channel is DEAD`);
+    }
+  }
+
+  /**
+   * Report an observed connection drop to the supervisor so it reconnects with
+   * bounded backoff. Adapters call this from their provider's close/error
+   * listener (the channel-adapter path). No-op when unsupervised.
+   * @param {string} [reason]
+   */
+  notifyConnectionDown(reason) {
+    try { this._supervisor?.notifyDown?.(reason); } catch { /* */ }
+  }
+
+  /**
+   * Run the pairing gate, intercept `pair <code>`, then forward to onInbound.
+   * Fail-open: any error here is logged and the event is dropped rather than
+   * crashing the loop (a single bad event must not take the channel down).
+   */
+  _handleEvent(ev) {
+    // Ownership / bot-loop backstop (P0-5): an inbound from the agent's OWN id
+    // or a KNOWN peer-agent id is never auto-replied — two collaborating agents
+    // in one channel would otherwise reply-storm. This runs in BOTH pairing
+    // modes, including "open" (Slack), where the bus factory now wires ownId /
+    // peerAgentIds but the directed-gate alone wouldn't stop a peer loop.
+    if (this._isOwnOrPeer(ev)) {
+      this._count(CHANNEL_COUNTERS.PEER_AGENT_DROPPED, { from: this._eventSenderId(ev) });
+      this.log("debug", `dropping own/peer-agent inbound (no auto-reply)`);
+      return;
+    }
+
+    // "open" channels (Slack) bypass the pairing gate — their membership and
+    // self/peer filtering already happened upstream (shouldKeepEvent) and the
+    // daemon's directed-gate governs the rest. Forwarding straight through
+    // keeps the live path byte-for-byte unchanged.
+    if (this.pairingMode === "open") {
+      try { this._onInbound(ev); }
+      catch (err) { this.log("error", `onInbound threw: ${err.message}`); }
+      return;
+    }
+
+    let gate;
+    try {
+      gate = checkAllowed(ev, {
+        agentRoot: this.agentRoot,
+        ownId: this.ownId,
+        peerAgentIds: this.peerAgentIds,
+      });
+    } catch (err) {
+      this.log("error", `pairing gate threw, dropping event: ${err.message}`);
+      return;
+    }
+
+    // `pair <code>` is intercepted BEFORE the classifier — it never reaches
+    // the inbox. Redeem it and (best-effort) acknowledge.
+    if (gate.isPairingCommand && gate.code) {
+      this._redeemAndAck(ev, gate.code);
+      return;
+    }
+
+    if (gate.allowed) {
+      try {
+        this._onInbound(ev);
+      } catch (err) {
+        this.log("error", `onInbound threw: ${err.message}`);
+      }
+      return;
+    }
+
+    // Denied. For an unknown DM sender, emit a single pairing prompt (once)
+    // so a legitimate human knows how to pair. Other reasons (self/peer) are
+    // silent drops.
+    if (gate.reason === "not-paired") {
+      this._maybePromptPairing(ev);
+    }
+    this.log("debug", `event dropped: ${gate.reason}`);
+  }
+
+  _redeemAndAck(ev, code) {
+    const source = ev.source || {};
+    const channel = source.channel || ev.channel || this.name;
+    const peerId = String(ev.from?.id ?? source.peerId ?? "");
+    let res = { ok: false, reason: "no-peer" };
+    try {
+      res = redeemPairing(channel, peerId, code, { agentRoot: this.agentRoot });
+    } catch (err) {
+      this.log("error", `redeemPairing threw: ${err.message}`);
+    }
+    // Best-effort acknowledgement back to the sender. This is a fixed,
+    // framework-authored control string (not model output and not user-facing
+    // content under disclosure/barrier policy), so it bypasses the outbound
+    // policy gate — otherwise the fail-closed external default would silently
+    // swallow the pairing handshake itself.
+    const text = res.ok
+      ? "Paired. You can message me here now."
+      : `That pairing code didn't work (${res.reason}). Ask for a fresh one.`;
+    this._systemSend({ to: source.chatId || peerId, text, source }).catch(() => {});
+    this.log("info", `pair attempt from ${peerId}: ${res.ok ? "ok" : res.reason}`);
+  }
+
+  _maybePromptPairing(ev) {
+    const peerId = String(ev.from?.id ?? ev.source?.peerId ?? "");
+    if (!peerId || this._promptedPeers.has(peerId)) return;
+    this._promptedPeers.add(peerId);
+    if (!this.onPairingPrompt) return;
+    Promise.resolve()
+      .then(() => this.onPairingPrompt(ev.source || { channel: this.name, chatId: peerId }))
+      .catch((err) => this.log("warn", `pairing prompt failed: ${err.message}`));
+  }
+
+  // -- ownership / bot-loop guard (P0-5) ------------------------------------
+
+  /** The sender peer id of an inbound event (best-effort, stringified). */
+  _eventSenderId(ev) {
+    return String(ev?.from?.id ?? ev?.source?.peerId ?? "");
+  }
+
+  /**
+   * Is this inbound from the agent's own id or a registered peer agent? Used to
+   * suppress self-echo and agent-to-agent reply storms in every pairing mode.
+   * @returns {boolean}
+   */
+  _isOwnOrPeer(ev) {
+    const id = this._eventSenderId(ev);
+    if (!id) return false;
+    if (this.ownId && id === String(this.ownId)) return true;
+    return this.peerAgentIds instanceof Set && this.peerAgentIds.has(id);
+  }
+
+  /**
+   * Sliding-window reply-storm guard. Records that we're about to send to a
+   * conversation and returns true if the per-conversation reply rate is over
+   * the ceiling inside the window — meaning we should suppress this send to
+   * break a ping-pong. Pruning is lazy (drop timestamps older than the window).
+   * Fail-open: any internal slip allows the send.
+   *
+   * @param {string} convKey  conversation key (channel:chatId:threadRef)
+   * @returns {boolean} true ⇒ suppress (storm); false ⇒ allow
+   */
+  _pairGuardTrips(convKey) {
+    try {
+      const now = Date.now();
+      const cutoff = now - PAIR_GUARD_WINDOW_MS;
+      const arr = (this._replyWindow.get(convKey) || []).filter((t) => t >= cutoff);
+      if (arr.length >= PAIR_GUARD_MAX) {
+        this._replyWindow.set(convKey, arr); // keep the pruned window
+        return true;
+      }
+      arr.push(now);
+      this._replyWindow.set(convKey, arr);
+      return false;
+    } catch {
+      return false; // fail-open: never let the guard itself block a send
+    }
+  }
+
+  // -- send / react ---------------------------------------------------------
+
+  /**
+   * Send an outbound message through the ONE shared outbound perimeter, then the
+   * adapter's _send.
+   *
+   * Order (gaps-product-quality P0-3/P0-5):
+   *   1. send-gate — the hook-bus `beforeSend` cancellable chain AND the shared
+   *      lib/comms/send-gate.screenOutbound. EITHER vetoing blocks the send.
+   *      Now EVERY adapter send passes the gate, not just Gmail.
+   *   2. pair guard — a per-conversation sliding window so two agents in one
+   *      channel can't reply-storm.
+   *   3. _send — the adapter transport.
+   *
+   * A blocked send returns a uniform SendResult `{ ok:false, blocked:true,
+   * reason }` (NOT thrown) so callers can branch on `res.blocked`.
+   *
+   * @param {object} out
+   * @returns {Promise<import("./contract.mjs").SendResult>}
+   */
+  async send(out) {
+    // 1. Outbound governance — the shared send-gate (hook-bus + screenOutbound).
+    if (this._sendGateEnabled) {
+      const gate = await this._screenSend(out);
+      if (!gate.allow) {
+        this._count(CHANNEL_COUNTERS.SEND_GATE_BLOCKED, { reason: gate.reason });
+        this.log("warn", `send blocked by gate: ${gate.reason}`);
+        return { ok: false, blocked: true, reason: gate.reason };
+      }
+      // The gate may rewrite the body (redaction); honour it.
+      if (typeof gate.text === "string" && gate.text !== out.text) {
+        out = { ...out, text: gate.text };
+      }
+    }
+
+    // 2. Bot-loop / reply-storm guard (per conversation).
+    const convKey = this._sendConvKey(out);
+    if (convKey && this._pairGuardTrips(convKey)) {
+      this._count(CHANNEL_COUNTERS.PAIR_GUARD_TRIPPED, { conversation: convKey });
+      this.log("warn", `send suppressed: reply-storm guard tripped for ${convKey}`);
+      return { ok: false, blocked: true, reason: "reply-storm-guard" };
+    }
+
+    // 3. Adapter transport.
+    try {
+      const res = await this._send(out);
+      // Normalise into a SendResult.
+      if (res && typeof res === "object" && "ok" in res) return res;
+      return { ok: true, message_id: res?.message_id, raw: res };
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  }
+
+  /**
+   * Send a fixed, framework-authored control message (pairing acks, prompts)
+   * that bypasses the outbound policy gate and the reply-storm guard. These are
+   * NOT model output and NOT user-facing content under disclosure/barrier
+   * policy, so gating them would only let the fail-closed external default
+   * swallow the pairing handshake. Errors are still shaped into a SendResult.
+   * @param {object} out
+   * @returns {Promise<import("./contract.mjs").SendResult>}
+   */
+  async _systemSend(out) {
+    try {
+      const res = await this._send(out);
+      if (res && typeof res === "object" && "ok" in res) return res;
+      return { ok: true, message_id: res?.message_id, raw: res };
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  }
+
+  /** Conversation key for the pair guard, derived from the outbound shape. */
+  _sendConvKey(out) {
+    const channel = out?.source?.channel || this.name;
+    const chatId = out?.to ?? out?.source?.chatId ?? "";
+    const threadRef = out?.thread_ref ?? out?.source?.threadRef ?? "";
+    if (chatId === "" || chatId == null) return "";
+    return `${channel}:${chatId}:${threadRef}`;
+  }
+
+  /**
+   * Run the shared outbound send-gate: the hook-bus `beforeSend` cancellable
+   * chain (so any subscriber — disclosure, custom policy — can veto) AND
+   * lib/comms/send-gate.screenOutbound (banned phrases, AI-disclosure,
+   * information barriers, allowlist). EITHER veto blocks.
+   *
+   * Fail posture: screenOutbound itself fails CLOSED for external recipients and
+   * OPEN for internal (it owns that policy). If our wiring around it throws
+   * unexpectedly we count a fail-open and allow — a buggy gate must never
+   * silently wedge all outbound traffic (house idiom), but the fail-open is
+   * LOUD (counted) so doctor/a human sees it.
+   *
+   * @returns {Promise<{allow:boolean, reason:string, text?:string}>}
+   */
+  async _screenSend(out) {
+    const channel = out?.source?.channel || this.name;
+    const recipient = String(out?.to ?? out?.source?.chatId ?? "");
+    const text = typeof out?.text === "string" ? out.text : "";
+
+    // (a) hook-bus beforeSend chain — only `beforeSend` is cancellable.
+    try {
+      const bus = this._bus();
+      if (bus) {
+        const res = await bus.emit("beforeSend", {
+          tool: `${this.name}_send`,
+          channel,
+          recipient,
+          text,
+          source: out?.source || null,
+        });
+        if (res && res.cancelled) {
+          return { allow: false, reason: res.reason || "beforeSend-cancelled" };
+        }
+      }
+    } catch (err) {
+      // A bus fault is fail-open (counted) — the screenOutbound layer below is
+      // the authoritative policy gate and runs regardless.
+      this._count(CHANNEL_COUNTERS.SEND_GATE_FAILOPEN, { stage: "hookbus", error: err && err.message });
+    }
+
+    // (b) the shared policy gate (the authoritative chokepoint).
+    try {
+      const verdict = await this._screenOutbound({
+        channel,
+        recipient,
+        text,
+        agentRoot: this.agentRoot,
+        jurisdiction: this._jurisdiction,
+        firstContact: out?.firstContact !== false,
+        internalDomains: this._internalDomains,
+        allowlist: Array.isArray(out?.allowlist) ? out.allowlist : undefined,
+      });
+      if (verdict && verdict.allow === false) {
+        return { allow: false, reason: verdict.reason || "blocked" };
+      }
+      return { allow: true, reason: "", text: verdict?.redactedText };
+    } catch (err) {
+      // screenOutbound is itself never supposed to throw (it has its own
+      // fail-closed/open policy). If our call site does, count the fail-open and
+      // allow rather than wedge every send — but loudly.
+      this._count(CHANNEL_COUNTERS.SEND_GATE_FAILOPEN, { stage: "screen", error: err && err.message });
+      this.log("error", `send-gate threw (fail-open): ${err && err.message}`);
+      return { allow: true, reason: "" };
+    }
+  }
+
+  async react(out) {
+    try {
+      return await this._react(out);
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  }
+
+  async setTyping(source, on) {
+    try {
+      await this._setTyping(source, on);
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, error: err.message };
+    }
+  }
+
+  // -- typing heartbeat -----------------------------------------------------
+
+  /**
+   * Start a typing heartbeat for a conversation. Calls `_setTyping(source,
+   * true)` immediately and then every ~4s until stopped. Each call is
+   * timeout-guarded so a hung provider can't wedge the interval. Keyed by the
+   * source's chat/thread so concurrent sessions don't collide.
+   *
+   * @param {import("./contract.mjs").SessionSource} source
+   * @returns {string} the heartbeat key (pass to stopTypingHeartbeat)
+   */
+  startTypingHeartbeat(source) {
+    if (!source) return "";
+    const key = this._typingKey(source);
+    if (this._typingTimers.has(key)) return key; // already beating
+
+    const beat = () => {
+      this._guardedTyping(source, true);
+    };
+    // Fire once immediately so the indicator shows without waiting a full tick.
+    beat();
+    const handle = this._setInterval(beat, this._typingIntervalMs);
+    if (handle && typeof handle.unref === "function") handle.unref();
+    this._typingTimers.set(key, handle);
+    return key;
+  }
+
+  /**
+   * Stop the typing heartbeat for a conversation and clear the indicator.
+   * @param {import("./contract.mjs").SessionSource|string} sourceOrKey
+   */
+  stopTypingHeartbeat(sourceOrKey) {
+    const key = typeof sourceOrKey === "string" ? sourceOrKey : this._typingKey(sourceOrKey);
+    const handle = this._typingTimers.get(key);
+    if (handle != null) {
+      this._clearInterval(handle);
+      this._typingTimers.delete(key);
+    }
+    // Best-effort clear of the indicator (channels where typing auto-expires
+    // can no-op _setTyping(false)).
+    if (typeof sourceOrKey === "object" && sourceOrKey) this._guardedTyping(sourceOrKey, false);
+  }
+
+  /** Stop every active typing heartbeat (called on stop()). */
+  stopAllTyping() {
+    for (const handle of this._typingTimers.values()) this._clearInterval(handle);
+    this._typingTimers.clear();
+  }
+
+  _typingKey(source) {
+    return `${source.channel || this.name}:${source.chatId || ""}:${source.threadRef || ""}`;
+  }
+
+  _guardedTyping(source, on) {
+    // Run _setTyping but never let it run longer than the guard window or
+    // reject into the interval; swallow + log.
+    let settled = false;
+    const timer = this._setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      this.log("debug", "typing call timed out");
+    }, DEFAULT_TYPING_CALL_TIMEOUT_MS);
+    if (timer && typeof timer.unref === "function") timer.unref();
+    Promise.resolve()
+      .then(() => this._setTyping(source, on))
+      .catch((err) => this.log("debug", `_setTyping failed: ${err.message}`))
+      .finally(() => {
+        settled = true;
+        this._clearTimeout(timer);
+      });
+  }
+
+  // -- lifecycle ------------------------------------------------------------
+
+  /**
+   * Liveness for the daemon health sweep. Reflects the reconnect supervisor's
+   * state so a dead channel reports RED instead of the old hardcoded green
+   * (P0-6: "nothing anywhere calls healthCheck; dead channels report healthy").
+   * A channel that has given up reconnecting is unhealthy; one that is down but
+   * still retrying is degraded-but-not-yet-dead (reported ok:false too so the
+   * sweep notices). Unsupervised adapters keep the prior always-ok behaviour.
+   */
+  async healthCheck() {
+    if (!this._superviseEnabled || !this._supervisor) {
+      return { ok: true, detail: `${this.name} adapter` };
+    }
+    const state = this._connState;
+    const ok = state === CONN_STATE.UP;
+    return {
+      ok,
+      state,
+      detail: ok
+        ? `${this.name} adapter (${state})`
+        : `${this.name} adapter ${state === CONN_STATE.GIVING_UP ? "DEAD" : "degraded"} (${state})`,
+    };
+  }
+
+  async stop() {
+    this._stopping = true;
+    try { this._supervisor?.stop?.("adapter-stop"); } catch { /* */ }
+    this.stopAllTyping();
+    this._replyWindow.clear();
+  }
+}
+
+/** Coerce peerAgentIds (Set | array | undefined) to a Set<string>. */
+function toPeerSet(v) {
+  if (v instanceof Set) return new Set([...v].map(String));
+  if (Array.isArray(v)) return new Set(v.map(String));
+  return new Set();
+}
+
+export default BaseAdapter;