@cohortapp/agent-sdk 2.3.2 → 2.4.1

package/lib/org/typing.mjs

@@ -0,0 +1,341 @@
+/**
+ * lib/org/typing.mjs — the agent-side "is composing…" indicator for Cohort.
+ *
+ * ## The gap this closes
+ *
+ * hq's in-process responder raises a typing indicator around every reply it
+ * composes (`llm-responder/dispatch.ts` withTyping). An SDK-driven agent could
+ * not: `pushTyping` is server-only and in-process, and the only external writer
+ * was the browser-session poll route. hq now also STANDS DOWN for any seat whose
+ * daemon beat inside 100s (`llm-responder/sdk-driven.ts`), so on exactly the
+ * conversations a real agent owns, the human saw nothing at all while the agent
+ * thought — for the tens of seconds a `claude --print` session takes. That reads
+ * as "the agent is broken", not "the agent is working".
+ *
+ * hq gained `messaging.typing` for this: a write-less RPC that publishes one
+ * ephemeral frame and returns the cadence to re-assert at. This module is the
+ * agent half.
+ *
+ * ## Shape: an adapter, not a new pipeline
+ *
+ * The daemon ALREADY starts/stops a typing heartbeat around every inbox-driven
+ * session (`scripts/daemon/dispatcher.mjs` → `typing-registry.startTyping(item)`
+ * on spawn, `stopTyping(item)` on close/error). That registry keys adapters by
+ * service name, and every channel adapter implements the same two methods from
+ * `lib/channels/base-adapter.mjs`:
+ *
+ *     startTypingHeartbeat(source) -> key
+ *     stopTypingHeartbeat(sourceOrKey)
+ *
+ * So the whole feature is one more adapter under the service name `cohort`,
+ * with the SAME interface — no new lifecycle, no new call sites, nothing to keep
+ * in sync. `sourceFromItem` (typing-registry) already yields
+ * `{channel:"cohort", chatId:<hq channelId>, threadRef:<threadRootId>}` for a
+ * cohort inbox item, which is exactly this method's params.
+ *
+ * ## Cadence
+ *
+ * The browser drops a typist ~5s after its last frame, so a long session must
+ * re-assert. We do NOT hardcode that: the first successful call returns
+ * `refreshAfterMs` and the heartbeat re-times itself to the server's answer
+ * (bounded by {@link MIN_INTERVAL_MS}/{@link MAX_INTERVAL_MS} so a bad server
+ * value cannot turn this into a hot loop or a dead indicator). Until an answer
+ * arrives we beat at {@link DEFAULT_INTERVAL_MS}.
+ *
+ * ## Fail-open, never silent
+ *
+ * Typing is cosmetic; nothing here may ever throw into the session path. Every
+ * failure resolves to `{ok:false, …}` and is LOGGED — but throttled per key
+ * ({@link LOG_THROTTLE_MS}), because an unreachable server would otherwise emit
+ * a line every 3s for the life of the session. Silent fail-open is what hid
+ * every previous bug in this pipeline; a 3s-interval logspam would hide the next
+ * one just as well.
+ *
+ * Node builtins only. ESM. `fetchImpl`/timer injection everywhere for tests.
+ *
+ * @module lib/org/typing
+ */
+
+"use strict";
+
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { call, configFromAgent, isEnabled, loadOrgConfig } from "./client.mjs";
+
+/** Beat cadence used until the server states its own `refreshAfterMs`. */
+export const DEFAULT_INTERVAL_MS = 3_000;
+/** Floor on the server-advised cadence — never beat faster than this. */
+export const MIN_INTERVAL_MS = 1_000;
+/** Ceiling on the server-advised cadence — beyond this the indicator blinks. */
+export const MAX_INTERVAL_MS = 15_000;
+/** One failure line per key per this window (see the header). */
+export const LOG_THROTTLE_MS = 60_000;
+/** org.yaml is re-read at most this often (it changes ~never). */
+const CONFIG_TTL_MS = 60_000;
+
+// ---------------------------------------------------------------------------
+// Config (cached — a 3s heartbeat must not stat + parse YAML every beat)
+// ---------------------------------------------------------------------------
+
+let _cfg = null;
+let _cfgAt = 0;
+let _cfgRoot = "";
+
+/** Drop the cached org config (tests / after re-enrolment). */
+export function resetTypingConfigCache() {
+  _cfg = null;
+  _cfgAt = 0;
+  _cfgRoot = "";
+}
+
+/**
+ * Resolve the agent's org config, cached for {@link CONFIG_TTL_MS}.
+ * @param {object} opts - { cfg?, agentRoot?, now? }
+ * @returns {object} the parsed org config ({} when un-enrolled)
+ */
+function resolveCfg(opts = {}) {
+  if (opts.cfg) return opts.cfg;
+  const root = resolveAgentRoot(opts.agentRoot);
+  const now = typeof opts.now === "number" ? opts.now : Date.now();
+  if (_cfg && _cfgRoot === root && now - _cfgAt < CONFIG_TTL_MS) return _cfg;
+  _cfg = loadOrgConfig(root) || {};
+  _cfgAt = now;
+  _cfgRoot = root;
+  return _cfg;
+}
+
+// ---------------------------------------------------------------------------
+// The single RPC
+// ---------------------------------------------------------------------------
+
+/**
+ * Publish one typing transition for this agent's seat.
+ *
+ * @param {object} o - {
+ *   channelId, threadRootId?, state? (default true),
+ *   cfg?, agentRoot?, fetchImpl?
+ * }
+ * @returns {Promise<{ok:boolean, skipped?:boolean, refreshAfterMs?:number,
+ *                    scopeKey?:string, error?:object}>}
+ */
+export async function emitTyping(o = {}) {
+  const channelId = o.channelId ? String(o.channelId) : "";
+  if (!channelId) {
+    return { ok: false, skipped: true, error: { code: "BAD_REQUEST", message: "missing channelId" } };
+  }
+  const cfg = resolveCfg(o);
+  // An un-enrolled agent has no org to type into. Not a fault, not logged.
+  if (!isEnabled(cfg)) return { ok: false, skipped: true };
+
+  const c = configFromAgent(cfg);
+  const params = { channelId, state: o.state === undefined ? true : !!o.state };
+  if (o.threadRootId) params.threadRootId = String(o.threadRootId);
+
+  const frame = await call("messaging.typing", params, {
+    base: c.base,
+    token: c.token,
+    orgId: c.orgId,
+    fetchImpl: o.fetchImpl,
+  });
+
+  if (!frame || frame.ok !== true) {
+    return { ok: false, error: (frame && frame.error) || { code: "INTERNAL", message: "no frame" } };
+  }
+  const result = frame.result || {};
+  return {
+    ok: true,
+    scopeKey: result.scopeKey,
+    refreshAfterMs: Number.isFinite(result.refreshAfterMs) ? result.refreshAfterMs : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The adapter (typing-registry / BaseAdapter interface)
+// ---------------------------------------------------------------------------
+
+/** `{chatId, threadRef}` → the heartbeat key. */
+function typingKey(source) {
+  const chat = source && source.chatId != null ? String(source.chatId) : "";
+  const thread = source && source.threadRef != null ? String(source.threadRef) : "";
+  return thread ? `${chat}|${thread}` : chat;
+}
+
+function clampInterval(ms) {
+  if (!Number.isFinite(ms)) return DEFAULT_INTERVAL_MS;
+  return Math.min(MAX_INTERVAL_MS, Math.max(MIN_INTERVAL_MS, ms));
+}
+
+/**
+ * Build a Cohort typing adapter with the same two-method surface every channel
+ * adapter exposes, so `scripts/daemon/typing-registry.mjs` can drive it with no
+ * special-casing.
+ *
+ * @param {object} opts - {
+ *   cfg?, agentRoot?, fetchImpl?, intervalMs?, log?,
+ *   setInterval?, clearInterval?, now?, emit?
+ * }
+ */
+export function createCohortTypingAdapter(opts = {}) {
+  const timers = new Map(); // key -> { handle, source }
+  const lastLogAt = new Map(); // key -> ms
+  const setIntervalFn = opts.setInterval || globalThis.setInterval;
+  const clearIntervalFn = opts.clearInterval || globalThis.clearInterval;
+  const nowFn = opts.now || Date.now;
+  const emit = opts.emit || emitTyping;
+  const log =
+    opts.log ||
+    ((msg) => {
+      try {
+        console.warn(`[org/typing] ${msg}`);
+      } catch {
+        /* never throw from logging */
+      }
+    });
+  let intervalMs = clampInterval(opts.intervalMs || DEFAULT_INTERVAL_MS);
+
+  /** Fail-open, throttled-loud. Never rejects. */
+  function beat(source, state) {
+    const key = typingKey(source);
+    return Promise.resolve()
+      .then(() =>
+        emit({
+          channelId: source && source.chatId,
+          threadRootId: source && source.threadRef,
+          state,
+          cfg: opts.cfg,
+          agentRoot: opts.agentRoot,
+          fetchImpl: opts.fetchImpl,
+        })
+      )
+      .then((res) => {
+        if (res && res.ok) {
+          if (res.refreshAfterMs) intervalMs = clampInterval(res.refreshAfterMs);
+          return res;
+        }
+        // `skipped` = un-enrolled / no channel id: a configuration state, not a
+        // failure — reporting it every 3s would be noise, not signal.
+        if (!res || !res.skipped) {
+          const code = (res && res.error && res.error.code) || "UNKNOWN";
+          const message = (res && res.error && res.error.message) || "";
+          const at = nowFn();
+          const last = lastLogAt.get(key);
+          // `undefined` (never logged) must always pass — a `|| 0` default
+          // swallows the FIRST report under any clock whose origin is 0.
+          if (last === undefined || at - last >= LOG_THROTTLE_MS) {
+            lastLogAt.set(key, at);
+            log(
+              `typing ${state ? "start" : "stop"} failed for ${key || "(no channel)"}: ` +
+                `${code} ${message} — the indicator is cosmetic, the session continues`
+            );
+          }
+        }
+        return res;
+      })
+      .catch((err) => {
+        // emitTyping itself is fail-open, so this is a programming error; still
+        // never propagate it into the session path.
+        const at = nowFn();
+        const last = lastLogAt.get(key);
+        if (last === undefined || at - last >= LOG_THROTTLE_MS) {
+          lastLogAt.set(key, at);
+          log(`typing beat threw for ${key || "(no channel)"}: ${err && err.message}`);
+        }
+        return { ok: false, error: { code: "INTERNAL", message: String(err && err.message) } };
+      });
+  }
+
+  return {
+    /** Service name this adapter registers under. */
+    service: "cohort",
+
+    /**
+     * Start beating "composing" for a conversation. Fires once immediately so
+     * the indicator appears within one RPC of the session spawning, then
+     * re-asserts on the server-advised cadence. Idempotent per key.
+     * @returns {string} the heartbeat key ("" when the source names no channel)
+     */
+    startTypingHeartbeat(source) {
+      const key = typingKey(source);
+      if (!key) return "";
+      if (timers.has(key)) return key; // already beating
+      // Register BEFORE the first await so a synchronous double-start can't
+      // create two intervals for one conversation.
+      const entry = { handle: null, source };
+      timers.set(key, entry);
+      void beat(source, true);
+      const handle = setIntervalFn(() => {
+        void beat(source, true);
+      }, intervalMs);
+      if (handle && typeof handle.unref === "function") handle.unref();
+      entry.handle = handle;
+      return key;
+    },
+
+    /** Stop the heartbeat and clear the indicator. Idempotent. */
+    stopTypingHeartbeat(sourceOrKey) {
+      const key = typeof sourceOrKey === "string" ? sourceOrKey : typingKey(sourceOrKey);
+      const entry = timers.get(key);
+      if (entry) {
+        if (entry.handle != null) clearIntervalFn(entry.handle);
+        timers.delete(key);
+      }
+      // Clear explicitly rather than waiting out the server-side TTL: the reply
+      // itself lands right after this, and "composing" must not outlive it.
+      const source =
+        typeof sourceOrKey === "object" && sourceOrKey
+          ? sourceOrKey
+          : entry && entry.source;
+      if (source) void beat(source, false);
+    },
+
+    /** Stop every active heartbeat (shutdown). */
+    stopAll() {
+      for (const [key, entry] of timers) {
+        if (entry.handle != null) clearIntervalFn(entry.handle);
+        if (entry.source) void beat(entry.source, false);
+        timers.delete(key);
+      }
+    },
+
+    /** Active heartbeat keys (introspection / tests). */
+    activeKeys() {
+      return [...timers.keys()];
+    },
+
+    /** The cadence currently in force (tests / diagnostics). */
+    get intervalMs() {
+      return intervalMs;
+    },
+  };
+}
+
+let _singleton = null;
+
+/**
+ * The process-wide Cohort typing adapter (created on first use). The daemon has
+ * exactly one agent seat, so one adapter is the right cardinality.
+ */
+export function cohortTypingAdapter(opts = {}) {
+  if (!_singleton) _singleton = createCohortTypingAdapter(opts);
+  return _singleton;
+}
+
+/** Drop the singleton (tests). */
+export function resetCohortTypingAdapter() {
+  if (_singleton) {
+    try {
+      _singleton.stopAll();
+    } catch {
+      /* best-effort */
+    }
+  }
+  _singleton = null;
+}
+
+export default {
+  emitTyping,
+  createCohortTypingAdapter,
+  cohortTypingAdapter,
+  resetCohortTypingAdapter,
+  resetTypingConfigCache,
+  DEFAULT_INTERVAL_MS,
+};

package/lib/org/typing.test.mjs

@@ -0,0 +1,291 @@
+/**
+ * typing.test.mjs — the agent-side "is composing…" indicator.
+ *
+ * Two units, both hermetic:
+ *   - emitTyping: params/URL/headers on the wire, the enrolment short-circuit,
+ *     and fail-open on an error frame (never throws, never claims ok).
+ *   - the adapter: immediate first beat, re-assert cadence adopted from the
+ *     server, idempotent start, stop clears the indicator, and — the property
+ *     that keeps this out of the session path — a permanently failing server
+ *     produces exactly one log line per throttle window, not one per beat.
+ *
+ * Uses an injected fetchImpl / emit + injected timers — no network, no clocks.
+ * Run: node --test lib/org/typing.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  emitTyping,
+  createCohortTypingAdapter,
+  cohortTypingAdapter,
+  resetCohortTypingAdapter,
+  resetTypingConfigCache,
+  DEFAULT_INTERVAL_MS,
+  MAX_INTERVAL_MS,
+  MIN_INTERVAL_MS,
+  LOG_THROTTLE_MS,
+} from "./typing.mjs";
+
+const BASE = "https://os.cohortapp.com";
+const CFG = { org: { cohort: { enabled: true, base: BASE, token: "tok", orgId: "adaptic" } } };
+const OFF = { org: { cohort: { enabled: false } } };
+
+delete process.env.COHORT_API_TOKEN;
+delete process.env.COHORT_TOKEN;
+
+/** A fake fetch that records calls and returns a canned res frame. */
+function fakeFetch(responder) {
+  const calls = [];
+  const impl = async (url, init) => {
+    calls.push({
+      url,
+      method: init && init.method,
+      headers: (init && init.headers) || {},
+      body: init && init.body ? JSON.parse(init.body) : null,
+    });
+    const r = responder ? responder(url, init, calls.length - 1) : null;
+    const status = r && typeof r.status === "number" ? r.status : 200;
+    const ok = r && typeof r.ok === "boolean" ? r.ok : status >= 200 && status < 300;
+    const body = r ? r.body : { ok: true, result: { ok: true, refreshAfterMs: 3000 } };
+    return { ok, status, headers: { get: () => undefined }, json: async () => body };
+  };
+  impl.calls = calls;
+  return impl;
+}
+
+/** Controllable interval timers. */
+function fakeTimers() {
+  const timers = new Map();
+  let next = 1;
+  return {
+    timers,
+    setInterval: (fn, ms) => {
+      const id = next++;
+      timers.set(id, { fn, ms });
+      return id;
+    },
+    clearInterval: (id) => timers.delete(id),
+    /** Fire every registered interval once. */
+    async tick() {
+      for (const t of [...timers.values()]) t.fn();
+      await new Promise((r) => setImmediate(r));
+    },
+  };
+}
+
+// --- emitTyping -------------------------------------------------------------
+
+test("emitTyping: posts messaging.typing with channelId + state, bearer + org pin", async () => {
+  const f = fakeFetch();
+  const r = await emitTyping({ channelId: "ch_1", cfg: CFG, fetchImpl: f });
+
+  assert.equal(r.ok, true);
+  assert.equal(r.refreshAfterMs, 3000);
+  assert.equal(f.calls.length, 1);
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/messaging.typing`);
+  assert.equal(f.calls[0].method, "POST");
+  assert.equal(f.calls[0].headers.authorization, "Bearer tok");
+  assert.equal(f.calls[0].headers["x-org-id"], "adaptic");
+  assert.deepEqual(f.calls[0].body, { channelId: "ch_1", state: true });
+});
+
+test("emitTyping: threadRootId rides through; state:false is a stop", async () => {
+  const f = fakeFetch();
+  await emitTyping({ channelId: "ch_1", threadRootId: "msg_root", state: false, cfg: CFG, fetchImpl: f });
+  assert.deepEqual(f.calls[0].body, { channelId: "ch_1", state: false, threadRootId: "msg_root" });
+});
+
+test("emitTyping: no channelId and un-enrolled both skip WITHOUT a request", async () => {
+  const f = fakeFetch();
+  const noChannel = await emitTyping({ cfg: CFG, fetchImpl: f });
+  assert.equal(noChannel.ok, false);
+  assert.equal(noChannel.skipped, true);
+
+  const off = await emitTyping({ channelId: "ch_1", cfg: OFF, fetchImpl: f });
+  assert.equal(off.ok, false);
+  assert.equal(off.skipped, true);
+
+  assert.equal(f.calls.length, 0);
+});
+
+test("emitTyping: an error frame fails open (no throw) and is NOT reported as skipped", async () => {
+  const f = fakeFetch(() => ({ status: 403, body: { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "not a member" } } }));
+  const r = await emitTyping({ channelId: "ch_1", cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, false);
+  assert.equal(r.skipped, undefined); // a real failure — the adapter must log it
+  assert.equal(r.error.code, "FORBIDDEN_SCOPE");
+});
+
+test("emitTyping: a dead transport fails open too", async () => {
+  const f = async () => {
+    throw new Error("ECONNREFUSED");
+  };
+  const r = await emitTyping({ channelId: "ch_1", cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, false);
+  assert.ok(r.error);
+});
+
+// --- the adapter ------------------------------------------------------------
+
+/** Adapter under test with injected emit + timers. */
+function makeAdapter(emitImpl, over = {}) {
+  const calls = [];
+  const logs = [];
+  const timers = fakeTimers();
+  const emit = async (o) => {
+    calls.push(o);
+    return emitImpl ? emitImpl(o, calls.length - 1) : { ok: true, refreshAfterMs: 3000 };
+  };
+  const adapter = createCohortTypingAdapter({
+    emit,
+    log: (m) => logs.push(m),
+    setInterval: timers.setInterval,
+    clearInterval: timers.clearInterval,
+    ...over,
+  });
+  return { adapter, calls, logs, timers };
+}
+
+const SOURCE = { channel: "cohort", chatId: "ch_1", threadRef: undefined, userScope: "channel" };
+
+test("startTypingHeartbeat: beats immediately, then on the interval", async () => {
+  const { adapter, calls, timers } = makeAdapter();
+  const key = adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+
+  assert.equal(key, "ch_1");
+  assert.equal(calls.length, 1, "the indicator must show without waiting a full tick");
+  assert.deepEqual({ channelId: calls[0].channelId, state: calls[0].state }, { channelId: "ch_1", state: true });
+
+  await timers.tick();
+  assert.equal(calls.length, 2);
+  assert.equal(calls[1].state, true);
+});
+
+test("start is idempotent per conversation; thread and channel are distinct keys", async () => {
+  const { adapter, timers } = makeAdapter();
+  adapter.startTypingHeartbeat(SOURCE);
+  adapter.startTypingHeartbeat(SOURCE);
+  assert.deepEqual(adapter.activeKeys(), ["ch_1"]);
+  assert.equal(timers.timers.size, 1);
+
+  adapter.startTypingHeartbeat({ chatId: "ch_1", threadRef: "msg_root" });
+  assert.deepEqual(adapter.activeKeys(), ["ch_1", "ch_1|msg_root"]);
+});
+
+test("stopTypingHeartbeat: clears the timer AND publishes state:false", async () => {
+  const { adapter, calls, timers } = makeAdapter();
+  adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+  adapter.stopTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+
+  assert.equal(timers.timers.size, 0);
+  assert.deepEqual(adapter.activeKeys(), []);
+  assert.equal(calls[calls.length - 1].state, false, "composing must not outlive the reply");
+});
+
+test("stopTypingHeartbeat by KEY still clears the indicator (dispatcher close path)", async () => {
+  const { adapter, calls } = makeAdapter();
+  const key = adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+  adapter.stopTypingHeartbeat(key);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(calls[calls.length - 1].state, false);
+});
+
+test("stop is idempotent and a stop for an unknown key is a no-op", async () => {
+  const { adapter } = makeAdapter();
+  adapter.stopTypingHeartbeat("never-started");
+  adapter.stopTypingHeartbeat(SOURCE);
+  assert.deepEqual(adapter.activeKeys(), []);
+});
+
+test("a source with no channel id never starts a heartbeat", () => {
+  const { adapter, timers } = makeAdapter();
+  assert.equal(adapter.startTypingHeartbeat({ chatId: "" }), "");
+  assert.equal(adapter.startTypingHeartbeat(null), "");
+  assert.equal(timers.timers.size, 0);
+});
+
+test("the cadence is the SERVER's answer, clamped to sane bounds", async () => {
+  const a = makeAdapter(() => ({ ok: true, refreshAfterMs: 4500 }));
+  a.adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(a.adapter.intervalMs, 4500);
+
+  const hot = makeAdapter(() => ({ ok: true, refreshAfterMs: 1 }));
+  hot.adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(hot.adapter.intervalMs, MIN_INTERVAL_MS, "a bad value must not become a hot loop");
+
+  const slow = makeAdapter(() => ({ ok: true, refreshAfterMs: 10 * 60_000 }));
+  slow.adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(slow.adapter.intervalMs, MAX_INTERVAL_MS, "a slow value must not blink the indicator");
+
+  const none = makeAdapter(() => ({ ok: true }));
+  none.adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+  assert.equal(none.adapter.intervalMs, DEFAULT_INTERVAL_MS);
+});
+
+test("a failing server logs ONCE per throttle window, never once per beat", async () => {
+  let now = 0;
+  const { adapter, logs, timers } = makeAdapter(
+    () => ({ ok: false, error: { code: "INTERNAL", message: "boom" } }),
+    { now: () => now }
+  );
+  adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+  for (let i = 0; i < 20; i++) {
+    now += 1_000;
+    await timers.tick();
+  }
+  assert.equal(logs.length, 1, "20 failed beats over 20s must not be 20 log lines");
+  assert.match(logs[0], /typing start failed for ch_1: INTERNAL boom/);
+
+  now += LOG_THROTTLE_MS;
+  await timers.tick();
+  assert.equal(logs.length, 2, "but a still-broken indicator must resurface each window");
+});
+
+test("a skipped (un-enrolled) beat is never logged — configuration is not failure", async () => {
+  const { adapter, logs, timers } = makeAdapter(() => ({ ok: false, skipped: true }));
+  adapter.startTypingHeartbeat(SOURCE);
+  await new Promise((r) => setImmediate(r));
+  await timers.tick();
+  assert.deepEqual(logs, []);
+});
+
+test("a throwing emit can never reach the session path", async () => {
+  const { adapter, logs } = makeAdapter(() => {
+    throw new Error("kaboom");
+  });
+  assert.doesNotThrow(() => adapter.startTypingHeartbeat(SOURCE));
+  await new Promise((r) => setImmediate(r));
+  assert.equal(logs.length, 1);
+  assert.match(logs[0], /threw/);
+});
+
+test("stopAll clears every heartbeat (daemon shutdown)", async () => {
+  const { adapter, timers } = makeAdapter();
+  adapter.startTypingHeartbeat({ chatId: "ch_1" });
+  adapter.startTypingHeartbeat({ chatId: "ch_2" });
+  adapter.stopAll();
+  assert.deepEqual(adapter.activeKeys(), []);
+  assert.equal(timers.timers.size, 0);
+});
+
+test("cohortTypingAdapter is a process singleton (one seat, one adapter)", () => {
+  resetCohortTypingAdapter();
+  const a = cohortTypingAdapter();
+  assert.equal(cohortTypingAdapter(), a);
+  resetCohortTypingAdapter();
+  assert.notEqual(cohortTypingAdapter(), a);
+  resetCohortTypingAdapter();
+  resetTypingConfigCache();
+});