privateer-agent 0.3.6 → 0.4.0

package/src/auth/privateer.ts

@@ -16,6 +16,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, rmSync }
 import { hostname, userInfo } from "node:os";
 import { globalDir, credentialsPath } from "../config/paths.ts";
 import { isAccountCapCode } from "../engine/errors.ts";
+import { terminalPublicKeyBase64 } from "../crypto/terminalKey.ts";
+import { pinAccountSignKey, clearAccountSignKey } from "../crypto/accountTrust.ts";
 
 // Default Privateer API host. NOTE: this is still the legacy "helix" Render
 // hostname the mobile/web client also points at (client/config/environment.ts);
@@ -118,13 +120,21 @@ let _refreshInFlight: Promise<ChildSession> | null = null;
 let _account: { accessToken: string } | null = null;
 
 export function loadCredentials(): Credentials | null {
-  if (_cache !== undefined) return _cache;
+  // Only a successfully-read credential is memoized. A NEGATIVE result (file absent
+  // or unreadable) is deliberately NOT cached: the credential can appear mid-session
+  // — the account /login writes credentials.json AFTER the extensions have already
+  // booted, and under jiti each extension gets its OWN module instance of this file,
+  // so a login's saveCredentials() never reaches another extension's `_cache`. If we
+  // memoized the pre-login "absent" as null, that instance would report "not signed
+  // in" forever (e.g. /remote-access refusing after a successful sign-in). Re-reading
+  // disk on each miss lets a later call see what a sign-in just wrote.
+  if (_cache) return _cache;
   const path = credentialsPath();
-  if (!existsSync(path)) return (_cache = null);
+  if (!existsSync(path)) return null;
   try {
     _cache = JSON.parse(readFileSync(path, "utf8")) as Credentials;
   } catch {
-    _cache = null;
+    return null;
   }
   return _cache;
 }
@@ -145,6 +155,9 @@ export function clearCredentials(): void {
   } catch {
     /* nothing to remove */
   }
+  // Drop the pinned account signing key too — it belongs to the account that just
+  // signed out; a different account must re-pin its own at link.
+  clearAccountSignKey();
   _cache = null;
   _child = null;
   _account = null;
@@ -192,6 +205,19 @@ function notifySessionExpired(): void {
   }
 }
 
+// A server-pushed `session_revoked` relay frame arrived: the account signed this
+// terminal out (from the app's Linked Devices). Treat it exactly like a lazily-
+// detected expiry — wipe the local machine login and announce it via
+// onSessionExpired — but PROMPTLY, while the process is live, instead of waiting
+// for the next authedFetch/launch to hit a 401. The relay owner additionally
+// drops remote access. No-op if we're already signed out, so a duplicate frame
+// (or a frame racing an in-flight /signout) doesn't fire a spurious notice.
+export function handleServerRevoke(): void {
+  if (!hasCredentials()) return;
+  clearCredentials();
+  notifySessionExpired();
+}
+
 // ── Sign-in notification ─────────────────────────────────────────────────────
 // Fired when a Privateer login completes on this terminal — the cue for the UI to
 // re-render its header/badge to the signed-in state. It reaches every sign-in entry
@@ -251,7 +277,17 @@ async function postJson(base: string, path: string, body: unknown, init: Request
 // Step 1: ask the server for a device + user code the human will approve in-app.
 export async function requestDeviceCode(deviceLabel = defaultDeviceLabel()): Promise<DeviceCode> {
   const base = serverBaseUrl();
-  const res = await postJson(base, "/auth/device/code", { deviceLabel });
+  // This terminal's public key rides the grant so the app can PIN it on approval
+  // (TOFU) — the trust anchor for later sealing secrets (channel tokens) that only
+  // this machine can open. Best-effort: if keygen fails we just omit it and the app
+  // falls back to terminal-only secret entry rather than blocking login.
+  let terminalPub: string | undefined;
+  try {
+    terminalPub = terminalPublicKeyBase64();
+  } catch {
+    /* no key → no app-sealed secrets for this terminal; login still proceeds */
+  }
+  const res = await postJson(base, "/auth/device/code", { deviceLabel, terminalPub });
   if (!res.ok) {
     throw new Error(`Couldn't start login (${res.status}). Check your connection or PRIVATEER_SERVER_URL.`);
   }
@@ -280,9 +316,12 @@ export async function pollForToken(
     const res = await postJson(base, "/auth/device/token", { device_code: code.device_code });
 
     if (res.ok) {
-      const data = (await res.json()) as Omit<Credentials, "serverBaseUrl">;
-      const creds: Credentials = { ...data, serverBaseUrl: base };
+      const data = (await res.json()) as Omit<Credentials, "serverBaseUrl"> & { accountSignPub?: string };
+      const creds: Credentials = { accessToken: data.accessToken, refreshToken: data.refreshToken, user: data.user, serverBaseUrl: base };
       saveCredentials(creds);
+      // Pin the account's signing public key (TOFU) so channel-config from the app can
+      // be verified as genuinely coming from the account, not a forging relay (F7/F8).
+      pinAccountSignKey(data.accountSignPub);
       notifySignedIn();
       return creds;
     }

package/src/channels/bridge.ts

@@ -0,0 +1,293 @@
+// The transport-agnostic core of the messaging channels — the analog of
+// RemoteBridge for the relay. It owns the policy that must be identical on every
+// platform:
+//   - allowlist    (who may drive the agent; fail-closed + silent to strangers)
+//   - serialization (one turn per conversation at a time; extra messages queue)
+//   - redaction     (chat platforms are external egress — scrub before send)
+//   - chunking      (respect the platform's per-message length cap)
+//
+// The agent itself is injected as `runTurn`, so this file stays Pi-free and
+// unit-testable against a fake adapter + fake runner (see tests/channels.test.ts).
+// The Pi-backed runner lives in ./run.ts.
+
+import type { ChannelAdapter, InboundMessage } from "./types.ts";
+
+// A minimal view of the permission request the gate hands us (see
+// src/permissions/gate.ts PermissionRequest). Kept local so the bridge doesn't
+// depend on the gate module.
+export interface ApprovalRequest {
+  kind: string;
+  title: string;
+  detail: string;
+}
+
+// Run one agent turn for a conversation. `onText` receives streamed text deltas as
+// they arrive; the bridge buffers/coalesces them. Resolves when the turn is done.
+// `signal` aborts a queued/in-flight turn (e.g. the user sent "/stop").
+export type TurnRunner = (
+  chatId: string,
+  text: string,
+  onText: (delta: string) => void,
+  signal: AbortSignal,
+  // The triggering user + their role, so the runner (and the gate it drives) can
+  // cap a member to read-only regardless of the channel's posture.
+  meta: TurnMeta,
+) => Promise<{ ok: boolean; error?: string }>;
+
+export interface TurnMeta {
+  userId: string;
+  isAdmin: boolean;
+}
+
+// A security-audit event. The bridge emits these at authorization-relevant moments;
+// run.ts appends them to an on-disk log. `detail` is redacted before it's emitted.
+export interface AuditEvent {
+  at: string;
+  event: "prompt" | "approval_request" | "approval_decision" | "interrupt" | "denied";
+  chatId: string;
+  userId?: string;
+  role?: "admin" | "member";
+  detail?: string;
+}
+
+export interface MessagingBridgeConfig {
+  adapter: ChannelAdapter;
+  runTurn: TurnRunner;
+  // Who may interact at all (admin OR member). False → ignored (fail-closed and
+  // SILENT: we don't confirm the bot exists to un-allowlisted senders).
+  isAllowed: (msg: InboundMessage) => boolean;
+  // Is this user an admin? Admins are governed by the channel posture and are the
+  // ONLY users whose yes/no resolves an approval. Members are read-only and can't
+  // approve.
+  isAdmin: (msg: InboundMessage) => boolean;
+  // Scrub secrets from every outbound message. Wired to redactText in ./run.ts.
+  redact?: (text: string) => string;
+  onLog?: (msg: string) => void;
+  // Optional append-only security audit sink.
+  onAudit?: (event: AuditEvent) => void;
+}
+
+// Stay comfortably under Telegram's 4096-char hard cap (Slack ~40k, Discord 2000 —
+// pick the tightest common bound for the shared path; a platform with a smaller cap
+// can override in its adapter later).
+const MAX_MSG = 1900;
+
+// How long to wait for a yes/no approval reply before failing closed (deny).
+const APPROVAL_TIMEOUT_MS = 120_000;
+
+const YES = new Set(["yes", "y", "allow", "ok", "okay", "approve", "approved", "👍", "✅"]);
+const NO = new Set(["no", "n", "deny", "denied", "stop", "cancel", "reject", "👎", "❌"]);
+
+// Interpret an approval reply. Returns null for anything that isn't a clear
+// yes/no, so the bridge can re-prompt instead of guessing (fail-safe: never treat
+// ambiguous text as allow).
+export function approvalDecision(text: string): "allow" | "deny" | null {
+  const t = text.trim().toLowerCase();
+  if (YES.has(t)) return "allow";
+  if (NO.has(t)) return "deny";
+  return null;
+}
+
+// The message a user sees when the agent wants to run a gated action.
+export function approvalPrompt(req: ApprovalRequest): string {
+  const detail = req.detail.length > 600 ? req.detail.slice(0, 600) + "\n…(truncated)" : req.detail;
+  return `⚠️ Approval needed — ${req.title} (${req.kind})\n\n${detail}\n\nReply "yes" to allow or "no" to deny (times out in 2 min).`;
+}
+
+// Split text into <=max chunks, preferring newline boundaries so code/paragraphs
+// aren't cut mid-line when possible.
+export function chunkText(text: string, max = MAX_MSG): string[] {
+  const out: string[] = [];
+  let rest = text;
+  while (rest.length > max) {
+    let cut = rest.lastIndexOf("\n", max);
+    if (cut < max * 0.5) cut = max; // no usable newline in the back half → hard cut
+    out.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^\n/, "");
+  }
+  if (rest) out.push(rest);
+  return out;
+}
+
+export class MessagingBridge {
+  // Per-chat promise tail: each new turn chains onto the previous so turns in the
+  // same conversation never interleave (they share one agent session downstream).
+  private readonly tails = new Map<string, Promise<void>>();
+  // Per-chat abort handle for the in-flight turn, so "/stop" can interrupt it.
+  private readonly aborts = new Map<string, AbortController>();
+  // Per-chat pending tool approval awaiting a yes/no reply. At most one at a time
+  // per chat (turns are serialized and a turn's tool calls are sequential).
+  private readonly approvals = new Map<string, (decision: "allow" | "deny") => void>();
+
+  constructor(private readonly cfg: MessagingBridgeConfig) {}
+
+  async start(): Promise<void> {
+    await this.cfg.adapter.start((m) => this.onMessage(m));
+    this.log(`channel "${this.cfg.adapter.name}" listening`);
+  }
+
+  stop(): void {
+    this.cfg.adapter.stop();
+    for (const a of this.aborts.values()) a.abort();
+    this.aborts.clear();
+    // Fail any pending approvals closed so no turn hangs on shutdown.
+    for (const resolve of this.approvals.values()) resolve("deny");
+    this.approvals.clear();
+  }
+
+  // Ask the user in `chatId` to approve a gated tool action, and await their yes/no
+  // reply. Wired to the permission gate's remote approver (see channels/run.ts): the
+  // gate suspends the tool until this resolves. Fail-closed — timeout, abort (/stop),
+  // or shutdown all resolve to "deny". Public because the gate calls it directly
+  // (via an AsyncLocalStorage handle to this bridge + the current chat id).
+  requestApproval(chatId: string, req: ApprovalRequest, signal?: AbortSignal): Promise<"allow" | "deny"> {
+    // Only one outstanding approval per chat; deny any stale one first.
+    this.approvals.get(chatId)?.("deny");
+
+    const prompt = approvalPrompt(req);
+    const detail = `${req.title}: ${req.detail}`;
+    this.cfg.onAudit?.({
+      at: new Date().toISOString(),
+      event: "approval_request",
+      chatId,
+      role: "admin", // approvals only arise from admin turns (members are read-only)
+      detail: this.cfg.redact ? this.cfg.redact(detail) : detail,
+    });
+    void this.cfg.adapter.sendText(chatId, this.cfg.redact ? this.cfg.redact(prompt) : prompt);
+
+    return new Promise<"allow" | "deny">((resolve) => {
+      let timer: ReturnType<typeof setTimeout>;
+      const settle = (decision: "allow" | "deny") => {
+        if (this.approvals.get(chatId) !== settle) return; // already settled
+        this.approvals.delete(chatId);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(decision);
+      };
+      const onAbort = () => {
+        void this.cfg.adapter.sendText(chatId, "🚫 request interrupted — denied.");
+        settle("deny");
+      };
+      timer = setTimeout(() => {
+        void this.cfg.adapter.sendText(chatId, "⌛ approval timed out — denied.");
+        settle("deny");
+      }, APPROVAL_TIMEOUT_MS);
+      this.approvals.set(chatId, settle);
+      if (signal) {
+        if (signal.aborted) return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  }
+
+  private log(msg: string): void {
+    this.cfg.onLog?.(msg);
+  }
+
+  private audit(m: InboundMessage, event: AuditEvent["event"], detail?: string): void {
+    if (!this.cfg.onAudit) return;
+    const red = detail && this.cfg.redact ? this.cfg.redact(detail) : detail;
+    this.cfg.onAudit({
+      at: new Date().toISOString(),
+      event,
+      chatId: m.chatId,
+      userId: m.userId,
+      role: this.cfg.isAdmin(m) ? "admin" : "member",
+      detail: red,
+    });
+  }
+
+  private onMessage(m: InboundMessage): void {
+    const text = m.text?.trim();
+    if (!text) return;
+
+    if (!this.cfg.isAllowed(m)) {
+      // Fail closed and stay silent — replying would confirm the bot to strangers.
+      this.log(`ignored message from unauthorized user ${m.userId} in chat ${m.chatId}`);
+      return;
+    }
+
+    // A pending tool approval in this chat consumes the next message as its answer —
+    // BEFORE the per-chat queue, because the turn awaiting approval is itself holding
+    // that queue open (routing the reply through the queue would deadlock it).
+    const pending = this.approvals.get(m.chatId);
+    if (pending) {
+      // Only admins may answer an approval. A member's reply is refused (and audited)
+      // — never silently treated as a decision.
+      if (!this.cfg.isAdmin(m)) {
+        this.audit(m, "denied", "non-admin attempted to answer an approval");
+        void this.cfg.adapter.sendText(m.chatId, "Only an admin can approve the pending action.");
+        return;
+      }
+      if (text === "/stop") {
+        this.audit(m, "approval_decision", "deny (/stop)");
+        pending("deny"); // interrupt while awaiting approval → deny it
+        return;
+      }
+      const decision = approvalDecision(text);
+      if (decision === null) {
+        void this.cfg.adapter.sendText(m.chatId, 'Reply "yes" to allow or "no" to deny the pending action.');
+        return;
+      }
+      this.audit(m, "approval_decision", decision);
+      pending(decision);
+      return;
+    }
+
+    // "/stop" interrupts the running turn instead of queueing another.
+    if (text === "/stop") {
+      this.aborts.get(m.chatId)?.abort();
+      return;
+    }
+
+    // Serialize per conversation: chain onto this chat's tail.
+    const prev = this.tails.get(m.chatId) ?? Promise.resolve();
+    const next = prev
+      .then(() => this.handle(m))
+      .catch((e) => this.log(`turn error: ${e instanceof Error ? e.message : String(e)}`));
+    this.tails.set(m.chatId, next);
+    // Drop the tail once this was the last queued turn, so the map doesn't grow.
+    void next.finally(() => {
+      if (this.tails.get(m.chatId) === next) this.tails.delete(m.chatId);
+    });
+  }
+
+  private async handle(m: InboundMessage): Promise<void> {
+    const { chatId } = m;
+    const isAdmin = this.cfg.isAdmin(m);
+    this.audit(m, "prompt", m.text.trim().slice(0, 200));
+    const ac = new AbortController();
+    this.aborts.set(chatId, ac);
+    this.cfg.adapter.sendTyping?.(chatId);
+
+    // Buffer the whole turn's text, then send once (coalesced) — the simplest
+    // correct choice. Streaming partial edits back to the channel is a future
+    // enhancement; buffering avoids a race between deltas and async sends and
+    // keeps this unit-testable without timers.
+    let buf = "";
+    let result: { ok: boolean; error?: string };
+    try {
+      result = await this.cfg.runTurn(chatId, m.text.trim(), (d) => (buf += d), ac.signal, {
+        userId: m.userId,
+        isAdmin,
+      });
+    } catch (e) {
+      result = { ok: false, error: e instanceof Error ? e.message : String(e) };
+    } finally {
+      this.aborts.delete(chatId);
+    }
+
+    const body = this.cfg.redact ? this.cfg.redact(buf) : buf;
+
+    // Deliver any text the turn produced (even on error — a partial answer is
+    // useful), then an error line if it failed.
+    if (body.trim()) {
+      for (const chunk of chunkText(body)) await this.cfg.adapter.sendText(chatId, chunk);
+    } else if (result.ok) {
+      await this.cfg.adapter.sendText(chatId, "✓ done (no text output).");
+    }
+    if (!result.ok) {
+      await this.cfg.adapter.sendText(chatId, `⚠️ ${result.error ?? "the agent hit an error"}`);
+    }
+  }
+}

package/src/channels/discord.ts

@@ -0,0 +1,210 @@
+// Discord channel adapter — templated off the others against the same
+// ChannelAdapter interface. Talks the Discord Gateway (a WebSocket) directly for
+// receive and the REST API for send, so — like Telegram/Slack — it needs NO public
+// inbound endpoint. Zero new dependencies: `ws` is already a dep (relayClient.ts)
+// and REST is fetch.
+//
+// Discord app setup (one-time):
+//   - Create a bot, copy its token → `botToken`.
+//   - Enable the MESSAGE CONTENT intent (privileged) in the dev portal, else
+//     `content` arrives empty.
+//   - Invite the bot to your server, or DM it. `allowFrom` lists Discord user ids.
+//
+// Everything above the adapter (allowlist, serialization, redaction, chunking) is
+// MessagingBridge, reused verbatim.
+
+import WebSocket from "ws";
+import type { ChannelAdapter, InboundMessage } from "./types.ts";
+
+const GATEWAY = "wss://gateway.discord.gg/?v=10&encoding=json";
+const API = "https://discord.com/api/v10";
+const RECONNECT_MS = 3000;
+const SEND_TIMEOUT_MS = 15_000;
+
+// Gateway intent bits we need: guild messages, DMs, and (privileged) message
+// content. https://discord.com/developers/docs/topics/gateway#gateway-intents
+const INTENT_GUILD_MESSAGES = 1 << 9;
+const INTENT_DIRECT_MESSAGES = 1 << 12;
+const INTENT_MESSAGE_CONTENT = 1 << 15;
+const DEFAULT_INTENTS = INTENT_GUILD_MESSAGES | INTENT_DIRECT_MESSAGES | INTENT_MESSAGE_CONTENT;
+
+interface DiscordMessage {
+  channel_id?: string;
+  content?: string;
+  author?: { id?: string; username?: string; bot?: boolean };
+}
+
+// Pure mapping: a MESSAGE_CREATE payload → normalized InboundMessage, or null.
+// Drops messages from ANY bot (`author.bot`, which includes our own) so the agent
+// never talks to itself. Extracted so it's unit-testable without the Gateway.
+export function messageFromDiscord(d: DiscordMessage): InboundMessage | null {
+  if (!d || !d.author || d.author.bot) return null;
+  if (typeof d.content !== "string" || !d.content || !d.channel_id || !d.author.id) return null;
+  return { chatId: d.channel_id, userId: d.author.id, userName: d.author.username, text: d.content };
+}
+
+export interface DiscordOptions {
+  botToken: string;
+  intents?: number;
+  fetchImpl?: typeof fetch;
+  onLog?: (msg: string) => void;
+}
+
+export class DiscordAdapter implements ChannelAdapter {
+  readonly name = "discord";
+  private readonly token: string;
+  private readonly intents: number;
+  private readonly fetchImpl: typeof fetch;
+  private readonly onLog?: (msg: string) => void;
+  private ws?: WebSocket;
+  private running = false;
+  private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private heartbeat?: ReturnType<typeof setInterval>;
+  private lastSeq: number | null = null; // last dispatch sequence (for heartbeats)
+  private acked = true; // did the server ack our last heartbeat? (zombie detection)
+  private onMessage?: (m: InboundMessage) => void;
+
+  constructor(opts: DiscordOptions) {
+    this.token = opts.botToken;
+    this.intents = opts.intents ?? DEFAULT_INTENTS;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.onLog = opts.onLog;
+  }
+
+  async start(onMessage: (m: InboundMessage) => void): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    this.onMessage = onMessage;
+    this.connect();
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.clearHeartbeat();
+    try {
+      this.ws?.close();
+    } catch {
+      /* ignore */
+    }
+    this.ws = undefined;
+  }
+
+  async sendText(chatId: string, text: string): Promise<void> {
+    if (!text) return;
+    const res = await this.fetchImpl(`${API}/channels/${chatId}/messages`, {
+      method: "POST",
+      headers: { authorization: `Bot ${this.token}`, "content-type": "application/json" },
+      body: JSON.stringify({ content: text }),
+      signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+    });
+    if (!res.ok) this.log(`create-message failed: HTTP ${res.status}`);
+  }
+
+  private log(msg: string): void {
+    this.onLog?.(`discord: ${msg}`);
+  }
+
+  private connect(): void {
+    if (!this.running) return;
+    const ws = new WebSocket(GATEWAY);
+    this.ws = ws;
+    ws.on("message", (raw) => this.handleFrame(ws, raw));
+    ws.on("close", () => {
+      if (this.ws === ws) this.ws = undefined;
+      this.clearHeartbeat();
+      if (this.running) this.scheduleReconnect();
+    });
+    ws.on("error", (err: Error) => this.log(`ws error: ${err?.message ?? err}`));
+  }
+
+  private scheduleReconnect(): void {
+    if (!this.running || this.reconnectTimer) return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined;
+      this.connect();
+    }, RECONNECT_MS);
+  }
+
+  private handleFrame(ws: WebSocket, raw: WebSocket.RawData): void {
+    let f: { op?: number; t?: string; s?: number | null; d?: any };
+    try {
+      f = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+    if (typeof f.s === "number") this.lastSeq = f.s;
+    switch (f.op) {
+      case 10: // Hello — begin heartbeating, then identify
+        this.startHeartbeat(ws, f.d?.heartbeat_interval ?? 41_250);
+        this.identify(ws);
+        break;
+      case 11: // Heartbeat ACK
+        this.acked = true;
+        break;
+      case 1: // server requested a heartbeat now
+        this.sendHeartbeat(ws);
+        break;
+      case 7: // Reconnect
+      case 9: // Invalid Session — drop and re-identify fresh (no resume, for simplicity)
+        try {
+          ws.close();
+        } catch {
+          /* ignore */
+        }
+        break;
+      case 0: // Dispatch
+        if (f.t === "MESSAGE_CREATE") {
+          const m = messageFromDiscord(f.d);
+          if (m) this.onMessage?.(m);
+        }
+        break;
+    }
+  }
+
+  private identify(ws: WebSocket): void {
+    this.send(ws, {
+      op: 2,
+      d: {
+        token: this.token,
+        intents: this.intents,
+        properties: { os: "linux", browser: "privateer", device: "privateer" },
+      },
+    });
+  }
+
+  private startHeartbeat(ws: WebSocket, intervalMs: number): void {
+    this.clearHeartbeat();
+    this.acked = true;
+    this.heartbeat = setInterval(() => {
+      if (!this.acked) {
+        // No ACK since the last beat → zombie connection; drop it to reconnect.
+        try {
+          ws.close();
+        } catch {
+          /* ignore */
+        }
+        return;
+      }
+      this.sendHeartbeat(ws);
+    }, intervalMs);
+  }
+
+  private sendHeartbeat(ws: WebSocket): void {
+    this.acked = false;
+    this.send(ws, { op: 1, d: this.lastSeq });
+  }
+
+  private clearHeartbeat(): void {
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    this.heartbeat = undefined;
+  }
+
+  private send(ws: WebSocket, payload: unknown): void {
+    try {
+      ws.send(JSON.stringify(payload));
+    } catch {
+      /* socket dying */
+    }
+  }
+}