@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/src/slack/router.ts

@@ -0,0 +1,285 @@
+// The inbound router: one Slack message -> one row, never a turn. The overseer
+// is retired (its duties moved to the companion, whose inbox is fed by the
+// daemon, not by Slack), so an inbound message reaches NO model: the router
+// refuses every message that clears the gates below with `dropped_no_overseer`.
+// Every drop is a ROW, not a log line — `slack_events` is the forensic record,
+// so "why did the bot ignore me?" is answerable from sqlite alone. Outbound
+// announcements and replies are unchanged.
+//
+// The checks run in a fixed order and each has exactly one disposition:
+//   1. channel   -> dropped_channel   (only cfg.slack.channel is ever handled)
+//   2. echo      -> dropped_echo      (three independent layers, see below;
+//                                      a user-less event lands here too — it is
+//                                      machine text, not a person)
+//   3. subtype   -> dropped_subtype   (only the plain message is a message)
+//   4. dedupe    -> dropped_dupe      (Slack redelivers on every missed ack)
+//   5. retired   -> dropped_no_overseer (a person's plain message: there is no
+//                                      session to hand it to)
+//
+// The router will never take a channel id from a message, nor a tier from
+// message text. Both come from config + the recorded Slack user id.
+import type { Config } from "../config.js";
+import type { SlackDisposition, SlackTier, StateStore } from "../state.js";
+import { isoSeconds } from "./messages.js";
+import type { SlackIdentity, SlackInboundEvent } from "./types.js";
+
+/** The header marker the overseer's appendix keys the Slack envelope off. */
+export const SLACK_INJECT_MARKER = "<!-- qcr:slack v1 -->";
+
+/**
+ * The only inbound shape the router treats as a plain message: one with no
+ * subtype (inbound turns are retired, so it ends as dropped_no_overseer).
+ * `message_changed` is the important one — an EDIT NEVER RE-TRIGGERS an answer, otherwise a user could rewrite history under an answer already
+ * given (and a bot editing its own message would loop).
+ */
+function isPlainMessage(ev: SlackInboundEvent): boolean {
+  return (
+    ev.type === "message" && (ev.subtype === undefined || ev.subtype === null || ev.subtype === "")
+  );
+}
+
+/** Has the daemon itself posted a message with this ts? (echo layer b) */
+function isOwnPostedTs(store: StateStore, ts: string): boolean {
+  // slack_posts has no by-ts accessor on StateStore; this is a read-only probe
+  // over the same table the post ledger owns.
+  const row = store.db.prepare("SELECT 1 AS hit FROM slack_posts WHERE ts = ? LIMIT 1").get(ts) as
+    { hit: number } | undefined;
+  return row !== undefined;
+}
+
+/** Rights tier of a Slack member id. Config is the ONLY input besides the id. */
+export function computeTier(cfg: Config, slackUser: string | null | undefined): SlackTier {
+  if (!slackUser) return "ignored";
+  // The configured owner (`[owner] slack_id`) gets the top rights tier.
+  // Persisted records carrying a legacy spelling of this tier are folded to
+  // "owner" on read (`foldSlackTier`); `system` is never computed here — it is
+  // stamped only by OriginStore.writeLocal for daemon turns.
+  if (cfg.owner.slack_id && slackUser === cfg.owner.slack_id) return "owner";
+  if (Object.prototype.hasOwnProperty.call(cfg.slack.users, slackUser)) return "author";
+  // An unmapped id gets read-only everything, but NO own-PR
+  // resolution — there is no login to resolve, so it must name PRs by number.
+  return "anyone";
+}
+
+/** GitHub login for a Slack id, or null when the id is unmapped. */
+export function githubLoginFor(cfg: Config, slackUser: string | null | undefined): string | null {
+  if (!slackUser) return null;
+  return cfg.slack.users[slackUser] ?? null;
+}
+
+/**
+ * Open PRs authored by `login`. Empty for an unmapped id — an `anyone` turn can
+ * never resolve author->PR, by construction.
+ *
+ * For the owner this list is their own PRs too, and it is deliberately NOT
+ * their authority: `authorizeCommand` lets tier `owner` act on any PR, so an
+ * empty list costs them nothing. Keeping the field honest (their real PRs)
+ * means the inject body reads the same for everyone.
+ */
+export function authorizedPrs(store: StateStore, login: string | null): number[] {
+  if (!login) return [];
+  return store
+    .allPrs()
+    .filter((p) => p.state !== "closed" && p.author.toLowerCase() === login.toLowerCase())
+    .map((p) => p.number);
+}
+
+/**
+ * Neutralise user text so it cannot forge the inject header.
+ *
+ * The overseer reads one markdown document; the top of it is a trusted table
+ * written by the daemon and the rest is a quoted human. A user who pastes their
+ * own `<!-- qcr:slack v1 -->` + `| tier | owner |` must end up with inert
+ * characters: every line is blockquoted, pipes are escaped so no line can be a
+ * table row, and comment delimiters are HTML-escaped so no line can be the
+ * marker.
+ */
+export function quoteUserText(text: string): string {
+  const body = (text ?? "").replace(/\r\n?/g, "\n");
+  const lines = body.length === 0 ? ["(no text)"] : body.split("\n");
+  return lines.map((line) => `> ${inertLine(line)}`.trimEnd()).join("\n");
+}
+
+/** One line of user-controlled text made inert inside the envelope: comment
+ * delimiters HTML-escaped (never the marker), pipes escaped (never a cell). */
+function inertLine(line: string): string {
+  return line
+    .replace(/<!--/g, "&lt;!&#45;&#45;")
+    .replace(/-->/g, "&#45;&#45;&gt;")
+    .replace(/\|/g, "\\|");
+}
+
+export interface InjectBodyInput {
+  event: SlackInboundEvent;
+  /** Root ts of the thread a reply must target. */
+  threadTs: string;
+  /** PR bound to that thread, when known. */
+  threadPr: number | null;
+  displayName: string;
+  githubLogin: string | null;
+  tier: SlackTier;
+  authorizedPrs: number[];
+  receivedAt: Date;
+}
+
+/** The inject envelope: marker, trusted field table, then the quoted message. */
+export function buildInjectBody(input: InjectBodyInput): string {
+  const dash = "—";
+  // The display name is user-chosen, so it gets the quoted body's escaping —
+  // it sits in the part of the envelope the appendix says to trust.
+  const displayName = inertLine(input.displayName.replace(/\s+/g, " "));
+  const rows: Array<[string, string]> = [
+    ["source", "slack"],
+    ["event_id", input.event.event_id],
+    ["channel", input.event.channel],
+    ["thread", input.threadTs],
+    ["thread_pr", input.threadPr === null ? dash : String(input.threadPr)],
+    ["slack_user", input.event.user ?? dash],
+    ["display_name", displayName],
+    ["github_login", input.githubLogin ?? dash],
+    ["tier", input.tier],
+    ["authorized_prs", input.authorizedPrs.length ? input.authorizedPrs.join(", ") : dash],
+    ["received_at", isoSeconds(input.receivedAt.toISOString())],
+  ];
+  const table = [
+    "| field | value |",
+    "| --- | --- |",
+    ...rows.map(([k, v]) => `| ${k} | ${v} |`),
+  ].join("\n");
+  const where = input.threadPr === null ? "in the channel" : `in thread for PR #${input.threadPr}`;
+  return [
+    SLACK_INJECT_MARKER,
+    table,
+    "",
+    `**${displayName}** ${where} said:`,
+    "",
+    quoteUserText(input.event.text),
+    "",
+    `Reply by writing a \`slack_reply\` command file with \`thread: "${input.threadTs}"\`.`,
+    `Your tier for this turn is **${input.tier}** — see the Slack appendix in your system prompt.`,
+    "",
+  ].join("\n");
+}
+
+export interface SlackRouterDeps {
+  cfg: Config;
+  store: StateStore;
+  /** Our own identity, resolved ONCE at boot (echo layer a). */
+  identity?: SlackIdentity | null;
+}
+
+export interface RouteResult {
+  disposition: SlackDisposition;
+  tier: SlackTier;
+  reason?: string;
+}
+
+export class SlackRouter {
+  constructor(private readonly deps: SlackRouterDeps) {}
+
+  /** Route one inbound event: one row, and never a turn. */
+  async handle(event: SlackInboundEvent): Promise<RouteResult> {
+    const cfg = this.deps.cfg;
+    const store = this.deps.store;
+    const tier = computeTier(cfg, event.user);
+
+    // (1) channel allowlist — a message from anywhere else is not our business.
+    if (event.channel !== cfg.slack.channel) {
+      return this.record(
+        event,
+        "ignored",
+        "dropped_channel",
+        `channel ${event.channel} is not the concierge channel`,
+      );
+    }
+
+    // (2) echo, three layers. (a) it is a bot / it is us, (b) we posted this ts.
+    const ownUserId = this.deps.identity?.user_id;
+    const ownBotId = this.deps.identity?.bot_id;
+    const looksLikeUs =
+      event.bot_id !== undefined ||
+      event.subtype === "bot_message" ||
+      (ownUserId !== undefined && event.user === ownUserId) ||
+      (ownBotId !== undefined && event.bot_id === ownBotId);
+    if (looksLikeUs || isOwnPostedTs(store, event.ts)) {
+      return this.record(
+        event,
+        "ignored",
+        "dropped_echo",
+        "message was posted by a bot (or by us)",
+      );
+    }
+
+    // (2b) no Slack user id ⇒ nobody asked anything. Such an event has no tier
+    //      (`computeTier` says `ignored`). It is machine-emitted text, which is
+    //      exactly what `dropped_echo` means.
+    if (tier === "ignored") {
+      return this.record(
+        event,
+        "ignored",
+        "dropped_echo",
+        "message carries no Slack user — not a person asking",
+      );
+    }
+
+    // (3) subtype allowlist — edits, deletions, joins and broadcasts are logged,
+    //     never answered.
+    if (!isPlainMessage(event)) {
+      return this.record(
+        event,
+        tier,
+        "dropped_subtype",
+        `subtype '${event.subtype ?? event.type}' is not answerable`,
+      );
+    }
+
+    // (4) dedupe, then (5) refuse. The row is written with its final
+    //     disposition in one insert, so a redelivery loses the race and reports
+    //     `dropped_dupe` while the original row stands. Nothing past this point
+    //     exists: the overseer a turn would have gone to is retired, so a plain
+    //     message from a person is recorded and goes no further.
+    return this.record(
+      event,
+      tier,
+      "dropped_no_overseer",
+      "Slack inbound turns are retired: there is no overseer to hand a message to",
+    );
+  }
+
+  /** Record a pre-dedupe drop. A redelivered drop reports `dropped_dupe` and
+   * leaves the original row (and its disposition) untouched. */
+  private record(
+    event: SlackInboundEvent,
+    tier: SlackTier,
+    disposition: SlackDisposition,
+    reason: string,
+  ): RouteResult {
+    if (!this.insertRow(event, tier, disposition)) return this.dupe(event, tier);
+    return { disposition, tier, reason };
+  }
+
+  /** Insert the event's dedupe row; false when the event id already has one. */
+  private insertRow(
+    event: SlackInboundEvent,
+    tier: SlackTier,
+    disposition: SlackDisposition,
+  ): boolean {
+    return this.deps.store.recordSlackEvent({
+      event_id: event.event_id,
+      channel: event.channel,
+      ts: event.ts,
+      thread_ts: event.thread_ts ?? null,
+      slack_user: event.user ?? null,
+      tier,
+      disposition,
+    });
+  }
+
+  private dupe(event: SlackInboundEvent, tier: SlackTier): RouteResult {
+    return {
+      disposition: "dropped_dupe",
+      tier,
+      reason: `event ${event.event_id} was already handled`,
+    };
+  }
+}

package/src/slack/socket.ts

@@ -0,0 +1,384 @@
+// Raw Socket Mode client — no @slack/socket-mode dependency: this
+// is a few hundred lines over Node's global WebSocket + fetch, both
+// injected so tests script frames deterministically.
+//
+// This file is PURE TRANSPORT. It acks, it reconnects, it normalizes — it does
+// not filter, dedupe or tier. That is the router's job.
+import diagnosticsChannel from "node:diagnostics_channel";
+import {
+  SLACK_API_BASE,
+  type SlackFetchFn,
+  type SlackInboundEvent,
+  type SlackInboundHandler,
+  type SlackSocket,
+} from "./types.js";
+
+/** The slice of the WebSocket API we use — global WebSocket satisfies it. */
+export interface SlackWebSocketLike {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  onopen: ((ev: unknown) => void) | null;
+  onmessage: ((ev: { data: unknown }) => void) | null;
+  onclose: ((ev: unknown) => void) | null;
+  onerror: ((ev: unknown) => void) | null;
+  /** A WebSocket-level ping frame arrived. Slack keeps a quiet connection
+   * alive with these, and they never reach `onmessage` — the global WebSocket
+   * answers them internally; `bridgeNativeWebSocketPings` surfaces them. */
+  onping?: (() => void) | null;
+}
+
+let pingBridgeInstalled = false;
+/** Sockets built by the native factory, for undici builds whose ping message
+ * does not say which socket it came from. */
+const bridgedSockets = new Set<SlackWebSocketLike>();
+
+/**
+ * Node's global WebSocket (undici) answers server pings itself and exposes
+ * them only on the `undici:websocket:ping` diagnostics channel. Newer undici
+ * (7+, Node 24+) carries the socket object; undici 6 — Node 22, older than
+ * the supported Node but not refused — carries ONLY the payload. So: a ping naming its socket reaches
+ * that socket's `onping`; a ping naming none reaches every live bridged
+ * socket (the Slack client is the process's only WebSocket user, so in
+ * practice that is exactly one). Idempotent.
+ */
+export function bridgeNativeWebSocketPings(): void {
+  if (pingBridgeInstalled) return;
+  pingBridgeInstalled = true;
+  diagnosticsChannel.subscribe("undici:websocket:ping", (msg) => {
+    const named = (msg as { websocket?: SlackWebSocketLike } | null)?.websocket;
+    const targets = named ? [named] : [...bridgedSockets];
+    for (const ws of targets) {
+      if (!ws.onping) {
+        bridgedSockets.delete(ws); // torn down: onping is nulled on close
+        continue;
+      }
+      try {
+        ws.onping();
+      } catch {
+        /* never let a hook throw into undici */
+      }
+    }
+  });
+}
+
+/** Register a natively-built socket with the ping bridge (see above). It
+ * leaves the bridge when the client tears it down or it closes. */
+export function trackBridgedSocket(ws: SlackWebSocketLike): void {
+  bridgedSockets.add(ws);
+}
+
+/** How many sockets the ping bridge holds (a diagnostics and test view). */
+export function bridgedSocketCount(): number {
+  return bridgedSockets.size;
+}
+
+export type SlackWebSocketFactory = (url: string) => SlackWebSocketLike;
+
+export interface SlackSocketOptions {
+  /** The app-level token (`xapp-…`) — apps.connections.open takes this one. */
+  appToken: string;
+  /** Injected fetch (default: global fetch). */
+  fetchFn?: SlackFetchFn;
+  /** Injected WebSocket constructor (default: global WebSocket). */
+  webSocketFactory?: SlackWebSocketFactory;
+  /** Jittered reconnect ladder in ms. */
+  backoffMs?: number[];
+  /** Tear down + reconnect when neither a frame nor a ping arrives for this long. */
+  serverPingTimeoutMs?: number;
+  /** Deadline for the whole `apps.connections.open` exchange (headers and
+   * body), ms: a stalled one is abandoned and the reconnect ladder takes over. */
+  openTimeoutMs?: number;
+  /** Web API base (override in tests). */
+  apiBase?: string;
+  /** Jitter source, [0,1). */
+  random?: () => number;
+  /** Timer seam. */
+  setTimeoutFn?: (fn: () => void, ms: number) => unknown;
+  clearTimeoutFn?: (handle: unknown) => void;
+  /** Structured log sink. */
+  log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+
+const DEFAULT_BACKOFF_MS = [1000, 2000, 5000, 15000, 30000];
+const DEFAULT_SERVER_PING_TIMEOUT_MS = 30_000;
+const DEFAULT_OPEN_TIMEOUT_MS = 15_000;
+
+export class SlackSocketClient implements SlackSocket {
+  private readonly appToken: string;
+  private readonly fetchFn: SlackFetchFn;
+  private readonly wsFactory: SlackWebSocketFactory;
+  private readonly backoff: number[];
+  private readonly pingTimeoutMs: number;
+  private readonly openTimeoutMs: number;
+  private readonly apiBase: string;
+  private readonly random: () => number;
+  private readonly setTimeoutFn: (fn: () => void, ms: number) => unknown;
+  private readonly clearTimeoutFn: (handle: unknown) => void;
+  private readonly log: (message: string, meta?: Record<string, unknown>) => void;
+
+  private handler: SlackInboundHandler | null = null;
+  private ws: SlackWebSocketLike | null = null;
+  private running = false;
+  private attempt = 0;
+  private reconnectTimer: unknown = null;
+  private watchdogTimer: unknown = null;
+  private connections = 0;
+
+  constructor(opts: SlackSocketOptions) {
+    this.appToken = opts.appToken;
+    this.fetchFn = opts.fetchFn ?? fetch;
+    this.wsFactory =
+      opts.webSocketFactory ??
+      ((url: string) => {
+        bridgeNativeWebSocketPings();
+        const ws = new WebSocket(url) as unknown as SlackWebSocketLike;
+        trackBridgedSocket(ws);
+        return ws;
+      });
+    this.backoff = opts.backoffMs?.length ? [...opts.backoffMs] : [...DEFAULT_BACKOFF_MS];
+    this.pingTimeoutMs = opts.serverPingTimeoutMs ?? DEFAULT_SERVER_PING_TIMEOUT_MS;
+    this.openTimeoutMs = opts.openTimeoutMs ?? DEFAULT_OPEN_TIMEOUT_MS;
+    this.apiBase = opts.apiBase ?? SLACK_API_BASE;
+    this.random = opts.random ?? Math.random;
+    this.setTimeoutFn = opts.setTimeoutFn ?? ((fn, ms) => setTimeout(fn, ms));
+    this.clearTimeoutFn =
+      opts.clearTimeoutFn ?? ((h) => clearTimeout(h as ReturnType<typeof setTimeout>));
+    this.log = opts.log ?? (() => {});
+  }
+
+  /** `num_connections` from the last `hello` frame. */
+  get numConnections(): number {
+    return this.connections;
+  }
+
+  async startSocket(handler: SlackInboundHandler): Promise<void> {
+    this.handler = handler;
+    this.running = true;
+    this.attempt = 0;
+    await this.connect();
+  }
+
+  async stopSocket(): Promise<void> {
+    this.running = false;
+    this.clearTimer("reconnectTimer");
+    this.clearTimer("watchdogTimer");
+    this.closeSocket();
+    this.handler = null;
+  }
+
+  // ---- connection lifecycle -------------------------------------------------
+
+  private async connect(): Promise<void> {
+    if (!this.running) return;
+    let url: string | undefined;
+    // The whole exchange runs under one deadline: a stalled open would
+    // otherwise hold startup, or silence a reconnect, with no watchdog armed.
+    const abort = new AbortController();
+    let deadline: unknown = null;
+    const timedOut = new Promise<never>((_resolve, reject) => {
+      deadline = this.setTimeoutFn(() => {
+        const err = new Error(`apps.connections.open timed out after ${this.openTimeoutMs}ms`);
+        abort.abort(err);
+        reject(err);
+      }, this.openTimeoutMs);
+    });
+    try {
+      const exchange = (async () => {
+        const res = await this.fetchFn(`${this.apiBase}/apps.connections.open`, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${this.appToken}`,
+            "content-type": "application/x-www-form-urlencoded",
+          },
+          signal: abort.signal,
+        });
+        return (await res.json()) as { ok?: boolean; url?: string; error?: string };
+      })();
+      exchange.catch(() => undefined); // settled by the race below either way
+      const body = await Promise.race([exchange, timedOut]);
+      if (body?.ok && typeof body.url === "string") url = body.url;
+      else this.log("slack.socket.open_failed", { error: body?.error ?? "no_url" });
+    } catch (err) {
+      this.log("slack.socket.open_threw", { error: String(err) });
+    } finally {
+      if (deadline !== null) this.clearTimeoutFn(deadline);
+    }
+    // stopSocket may have run while the open was in flight: it found no socket
+    // to close, so building one now would leak it onto a stopped client.
+    if (!this.running) return;
+    if (!url) {
+      this.scheduleReconnect();
+      return;
+    }
+
+    let ws: SlackWebSocketLike;
+    try {
+      ws = this.wsFactory(url);
+    } catch (err) {
+      this.log("slack.socket.ws_construct_failed", { error: String(err) });
+      this.scheduleReconnect();
+      return;
+    }
+    this.ws = ws;
+    ws.onopen = () => {
+      this.attempt = 0;
+      this.log("slack.socket.open");
+      this.armWatchdog();
+    };
+    ws.onmessage = (ev) => this.onFrame(ev?.data);
+    ws.onping = () => {
+      if (this.ws === ws) this.armWatchdog(); // a server ping is liveness too
+    };
+    ws.onerror = (err) => this.log("slack.socket.error", { error: String(err) });
+    ws.onclose = () => {
+      ws.onping = null; // closed: no ping may count as liveness any more
+      bridgedSockets.delete(ws);
+      if (this.ws !== ws) return; // a stale socket we already replaced
+      this.ws = null;
+      this.clearTimer("watchdogTimer");
+      if (this.running) this.scheduleReconnect();
+    };
+    this.armWatchdog();
+  }
+
+  private closeSocket(): void {
+    const ws = this.ws;
+    this.ws = null;
+    if (!ws) return;
+    ws.onopen = null;
+    ws.onmessage = null;
+    ws.onclose = null;
+    ws.onerror = null;
+    ws.onping = null;
+    bridgedSockets.delete(ws);
+    try {
+      ws.close();
+    } catch {
+      /* already gone */
+    }
+  }
+
+  /** Reconnect now-ish (fresh ladder) — used for `disconnect` frames. */
+  private reconnectNow(reason: string): void {
+    this.log("slack.socket.reconnect", { reason });
+    this.clearTimer("watchdogTimer");
+    this.closeSocket();
+    this.attempt = 0;
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.running || this.reconnectTimer !== null) return;
+    const idx = Math.min(this.attempt, this.backoff.length - 1);
+    const base = this.backoff[idx] ?? DEFAULT_BACKOFF_MS[0]!;
+    this.attempt += 1;
+    // Full jitter over the upper half of the rung: [base/2, base].
+    const delay = Math.round(base / 2 + this.random() * (base / 2));
+    this.log("slack.socket.reconnect_scheduled", { delay, attempt: this.attempt });
+    this.reconnectTimer = this.setTimeoutFn(() => {
+      this.reconnectTimer = null;
+      void this.connect();
+    }, delay);
+  }
+
+  private armWatchdog(): void {
+    this.clearTimer("watchdogTimer");
+    if (!this.running) return;
+    this.watchdogTimer = this.setTimeoutFn(() => {
+      this.watchdogTimer = null;
+      this.log("slack.socket.ping_timeout", { timeout_ms: this.pingTimeoutMs });
+      this.closeSocket();
+      this.scheduleReconnect();
+    }, this.pingTimeoutMs);
+  }
+
+  private clearTimer(which: "reconnectTimer" | "watchdogTimer"): void {
+    const handle = this[which];
+    if (handle !== null) {
+      this.clearTimeoutFn(handle);
+      this[which] = null;
+    }
+  }
+
+  // ---- frames ---------------------------------------------------------------
+
+  private onFrame(raw: unknown): void {
+    this.armWatchdog(); // any frame from the server counts as liveness
+    let frame: SocketFrame;
+    try {
+      frame = JSON.parse(typeof raw === "string" ? raw : String(raw)) as SocketFrame;
+      if (frame === null || typeof frame !== "object" || Array.isArray(frame))
+        throw new Error("invalid frame");
+    } catch {
+      this.log("slack.socket.bad_frame");
+      return;
+    }
+
+    // ACK FIRST — within 3s, before any processing. The ack means "received",
+    // never "handled"; processing is async and may still fail.
+    if (typeof frame.envelope_id === "string" && frame.envelope_id) {
+      try {
+        this.ws?.send(JSON.stringify({ envelope_id: frame.envelope_id }));
+      } catch (err) {
+        this.log("slack.socket.ack_failed", { error: String(err) });
+      }
+    }
+
+    switch (frame.type) {
+      case "hello":
+        this.connections = typeof frame.num_connections === "number" ? frame.num_connections : 0;
+        this.log("slack.socket.hello", { num_connections: this.connections });
+        return;
+      case "disconnect":
+        this.reconnectNow(frame.reason ?? "unknown");
+        return;
+      case "events_api":
+        this.onEventsApi(frame);
+        return;
+      default:
+        return; // slash_commands, interactive, anything else: not ours
+    }
+  }
+
+  private onEventsApi(frame: SocketFrame): void {
+    const payload = frame.payload;
+    const event = payload?.event;
+    if (!event || event.type !== "message") return;
+    const normalized: SlackInboundEvent = {
+      event_id: String(payload?.event_id ?? frame.envelope_id ?? ""),
+      type: "message",
+      channel: String(event.channel ?? ""),
+      ts: String(event.ts ?? ""),
+      ...(event.thread_ts !== undefined ? { thread_ts: String(event.thread_ts) } : {}),
+      ...(event.user !== undefined ? { user: String(event.user) } : {}),
+      text: typeof event.text === "string" ? event.text : "",
+      ...(event.subtype !== undefined ? { subtype: String(event.subtype) } : {}),
+      ...(event.bot_id !== undefined ? { bot_id: String(event.bot_id) } : {}),
+      event_ts: String(event.event_ts ?? payload?.event_time ?? event.ts ?? ""),
+    };
+    const handler = this.handler;
+    if (!handler) return;
+    // Deferred to a microtask: the ack is already on the wire, and nothing the
+    // handler does (however slow, however throwing) can delay or undo it.
+    void Promise.resolve()
+      .then(() => handler(normalized))
+      .catch((err: unknown) => {
+        this.log("slack.socket.handler_failed", {
+          error: String(err),
+          event_id: normalized.event_id,
+        });
+      });
+  }
+}
+
+interface SocketFrame {
+  type?: string;
+  envelope_id?: string;
+  reason?: string;
+  num_connections?: number;
+  payload?: {
+    event_id?: string;
+    event_time?: number;
+    event?: Record<string, unknown> & { type?: string };
+  };
+}