lunibee 0.1.6 → 0.1.8

package/dist/sharding/index.js

@@ -1,5 +1,702 @@
 // @bun
-// packages/types/src/index.ts
+// packages/ws/src/session.ts
+class GatewaySession {
+  #state = { status: "none" };
+  #sequence = null;
+  #generation = 0;
+  #lastInvalidation;
+  get lastInvalidation() {
+    return this.#lastInvalidation;
+  }
+  get generation() {
+    return this.#generation;
+  }
+  get sessionId() {
+    return this.#state.status === "established" ? this.#state.sessionId : undefined;
+  }
+  get resumeURL() {
+    return this.#state.status === "established" ? this.#state.resumeURL : undefined;
+  }
+  get sequence() {
+    return this.#sequence;
+  }
+  get canResume() {
+    return this.#state.status === "established" && this.#sequence !== null;
+  }
+  beginConnection() {
+    return ++this.#generation;
+  }
+  owns(token) {
+    return token === this.#generation;
+  }
+  recordSequence(sequence, token) {
+    if (!this.owns(token))
+      return false;
+    if (!Number.isInteger(sequence))
+      return false;
+    this.#sequence = sequence;
+    return true;
+  }
+  activate(payload, token) {
+    if (!this.owns(token))
+      return false;
+    const ready = payload;
+    if (typeof ready?.session_id !== "string" || typeof ready?.resume_gateway_url !== "string")
+      return false;
+    this.#state = {
+      status: "established",
+      sessionId: ready.session_id,
+      resumeURL: ready.resume_gateway_url
+    };
+    return true;
+  }
+  invalidate(token, reason = "explicit") {
+    if (!this.owns(token))
+      return false;
+    this.#lastInvalidation = reason;
+    this.#state = { status: "none" };
+    this.#sequence = null;
+    return true;
+  }
+  resumeInfo() {
+    if (this.#state.status !== "established")
+      return;
+    if (this.#sequence === null)
+      return;
+    const { sessionId, resumeURL } = this.#state;
+    return { sessionId, sequence: this.#sequence, resumeURL };
+  }
+  handshake() {
+    const resume = this.resumeInfo();
+    return resume ? { type: "resume", ...resume } : { type: "identify" };
+  }
+  connectURL(fallback) {
+    return this.resumeInfo()?.resumeURL ?? fallback;
+  }
+}
+
+// packages/ws/src/heartbeat.ts
+var MAX_MONITOR_INTERVAL = 1000;
+
+class GatewayHeartbeat {
+  #options;
+  #now;
+  #interval = 0;
+  #acknowledged = true;
+  #sentAt = 0;
+  #latency = -1;
+  #lastMessageAt = 0;
+  #zombieReported = false;
+  #timer;
+  #initialTimer;
+  #ackTimer;
+  #monitorTimer;
+  constructor(options) {
+    if (options.zombieTimeout <= options.ackTimeout)
+      throw new RangeError("Gateway zombieTimeout must be greater than heartbeatAckTimeout");
+    this.#options = options;
+    this.#now = options.now ?? (() => Date.now());
+  }
+  get latency() {
+    return this.#latency;
+  }
+  get interval() {
+    return this.#interval;
+  }
+  get acknowledged() {
+    return this.#acknowledged;
+  }
+  get silentFor() {
+    return this.#lastMessageAt === 0 ? 0 : this.#now() - this.#lastMessageAt;
+  }
+  get stalenessDeadline() {
+    return Math.max(this.#options.zombieTimeout, this.#interval + this.#options.ackTimeout);
+  }
+  isHealthy() {
+    if (!this.#acknowledged)
+      return false;
+    if (this.#lastMessageAt === 0)
+      return true;
+    return this.silentFor < this.stalenessDeadline;
+  }
+  watch() {
+    this.#lastMessageAt = this.#now();
+    this.#zombieReported = false;
+    this.#startMonitor();
+  }
+  receivedMessage() {
+    this.#lastMessageAt = this.#now();
+    this.#zombieReported = false;
+  }
+  start(interval) {
+    this.#clearBeatTimers();
+    this.#interval = interval;
+    this.#acknowledged = true;
+    this.#initialTimer = setTimeout(() => this.sendHeartbeat(), Math.random() * interval);
+    this.#timer = setInterval(() => this.sendHeartbeat(), interval);
+  }
+  stop() {
+    this.#clearBeatTimers();
+    if (this.#monitorTimer)
+      clearInterval(this.#monitorTimer);
+    this.#monitorTimer = undefined;
+  }
+  sendHeartbeat() {
+    this.#acknowledged = false;
+    this.#sentAt = this.#now();
+    if (!this.#options.send(this.#options.sequence())) {
+      this.#options.onError(new Error("Unable to send Gateway heartbeat because the WebSocket is not open."));
+      return;
+    }
+    this.#clearAckTimer();
+    this.#ackTimer = setTimeout(() => {
+      if (this.#acknowledged)
+        return;
+      this.#options.onTimeout({
+        type: "ack",
+        elapsedMs: this.#now() - this.#sentAt
+      });
+    }, this.#options.ackTimeout);
+  }
+  acknowledge() {
+    this.#acknowledged = true;
+    this.#latency = this.#now() - this.#sentAt;
+    this.#clearAckTimer();
+  }
+  #startMonitor() {
+    if (this.#monitorTimer)
+      clearInterval(this.#monitorTimer);
+    const interval = Math.max(1, Math.min(MAX_MONITOR_INTERVAL, this.#options.ackTimeout, this.#options.zombieTimeout / 2));
+    this.#monitorTimer = setInterval(() => this.#checkStaleness(), interval);
+  }
+  #checkStaleness() {
+    if (!this.#options.isConnected() || this.#lastMessageAt === 0)
+      return;
+    const silentFor = this.silentFor;
+    const deadline = this.stalenessDeadline;
+    if (silentFor < deadline || this.#zombieReported)
+      return;
+    this.#zombieReported = true;
+    this.#options.onTimeout({ type: "zombie", silentFor, deadline });
+  }
+  #clearAckTimer() {
+    if (this.#ackTimer)
+      clearTimeout(this.#ackTimer);
+    this.#ackTimer = undefined;
+  }
+  #clearBeatTimers() {
+    if (this.#timer)
+      clearInterval(this.#timer);
+    if (this.#initialTimer)
+      clearTimeout(this.#initialTimer);
+    this.#clearAckTimer();
+    this.#timer = undefined;
+    this.#initialTimer = undefined;
+  }
+}
+
+// packages/ws/src/close-codes.ts
+var GatewayCloseCodes = {
+  UnknownError: 4000,
+  UnknownOpcode: 4001,
+  DecodeError: 4002,
+  NotAuthenticated: 4003,
+  AuthenticationFailed: 4004,
+  AlreadyAuthenticated: 4005,
+  InvalidSeq: 4007,
+  RateLimited: 4008,
+  SessionTimedOut: 4009,
+  InvalidShard: 4010,
+  ShardingRequired: 4011,
+  InvalidAPIVersion: 4012,
+  InvalidIntents: 4013,
+  DisallowedIntents: 4014
+};
+
+// packages/ws/src/reconnect.ts
+var FATAL_CLOSE_CODES = [
+  GatewayCloseCodes.AuthenticationFailed,
+  GatewayCloseCodes.InvalidShard,
+  GatewayCloseCodes.ShardingRequired,
+  GatewayCloseCodes.InvalidAPIVersion,
+  GatewayCloseCodes.InvalidIntents,
+  GatewayCloseCodes.DisallowedIntents
+];
+var IDENTIFY_CLOSE_CODES = [
+  GatewayCloseCodes.InvalidSeq,
+  GatewayCloseCodes.SessionTimedOut
+];
+function classifyCloseCode(code, canResume) {
+  if (FATAL_CLOSE_CODES.includes(code))
+    return "stop";
+  if (IDENTIFY_CLOSE_CODES.includes(code))
+    return "identify";
+  return canResume ? "resume" : "identify";
+}
+
+class GatewayReconnect {
+  #options;
+  #random;
+  #attempt = 0;
+  #timer;
+  #promise;
+  #resolve;
+  #reject;
+  constructor(options) {
+    this.#options = options;
+    this.#random = options.random ?? Math.random;
+  }
+  get enabled() {
+    return this.#options.enabled;
+  }
+  get attempts() {
+    return this.#attempt;
+  }
+  get pending() {
+    return this.#timer !== undefined;
+  }
+  get exhausted() {
+    return this.#attempt >= this.#options.maxAttempts;
+  }
+  get connecting() {
+    return this.#promise !== undefined;
+  }
+  get attemptPromise() {
+    return this.#promise;
+  }
+  classifyClose(code, canResume) {
+    return classifyCloseCode(code, canResume);
+  }
+  canReconnect() {
+    return this.#options.enabled && !this.exhausted;
+  }
+  schedule(run) {
+    if (!this.#options.enabled)
+      return { scheduled: false, reason: "disabled" };
+    if (this.#timer)
+      return { scheduled: false, reason: "pending" };
+    if (this.exhausted)
+      return { scheduled: false, reason: "exhausted" };
+    const attempt = this.#attempt;
+    const delay = Math.min(this.#options.maxDelay, this.#options.baseDelay * 2 ** this.#attempt++);
+    const jitter = this.#random() * Math.max(1, delay * 0.25);
+    const delayMs = delay + jitter;
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined;
+      run();
+    }, delayMs);
+    return { scheduled: true, delayMs, attempt };
+  }
+  cancel() {
+    if (this.#timer)
+      clearTimeout(this.#timer);
+    this.#timer = undefined;
+  }
+  reset() {
+    this.#attempt = 0;
+  }
+  attempt(start) {
+    if (this.#promise)
+      return this.#promise;
+    this.#promise = new Promise((resolve, reject) => {
+      this.#resolve = resolve;
+      this.#reject = reject;
+      start();
+    });
+    return this.#promise;
+  }
+  settle(error) {
+    const resolve = this.#resolve;
+    const reject = this.#reject;
+    this.#resolve = undefined;
+    this.#reject = undefined;
+    this.#promise = undefined;
+    if (error)
+      reject?.(error);
+    else
+      resolve?.();
+  }
+}
+
+// packages/ws/src/decoder.ts
+import {
+  createInflate,
+  constants as zlibConstants
+} from "zlib";
+async function toBytes(data) {
+  if (data instanceof Uint8Array)
+    return data;
+  if (data instanceof ArrayBuffer)
+    return new Uint8Array(data);
+  if (typeof Blob !== "undefined" && data instanceof Blob)
+    return new Uint8Array(await data.arrayBuffer());
+  throw new TypeError("Gateway returned an unsupported compressed frame type.");
+}
+
+class PlainTextDecoder {
+  push(data) {
+    return [String(data)];
+  }
+  reset() {}
+}
+
+class ZlibStreamDecoder {
+  #create;
+  #inflate;
+  #chunks = [];
+  #failure;
+  #pendingReject;
+  constructor(create = () => createInflate()) {
+    this.#create = create;
+  }
+  push(data) {
+    if (typeof data === "string")
+      return [data];
+    return this.#inflateFrame(data);
+  }
+  async#inflateFrame(data) {
+    const chunk = await toBytes(data);
+    const inflate = this.#inflate ??= this.#open();
+    if (this.#failure)
+      throw this.#failure;
+    const complete = chunk.length >= 4 && chunk[chunk.length - 4] === 0 && chunk[chunk.length - 3] === 0 && chunk[chunk.length - 2] === 255 && chunk[chunk.length - 1] === 255;
+    await this.#awaiting((settle) => inflate.write(chunk, (error) => error ? settle(error) : settle()));
+    if (!complete)
+      return [];
+    await this.#awaiting((settle) => inflate.flush(zlibConstants.Z_SYNC_FLUSH, () => settle()));
+    const parts = this.#chunks;
+    this.#chunks = [];
+    if (parts.length === 0)
+      return [];
+    const total = parts.reduce((size, part) => size + part.length, 0);
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+      merged.set(part, offset);
+      offset += part.length;
+    }
+    return [new TextDecoder().decode(merged)];
+  }
+  reset() {
+    const inflate = this.#inflate;
+    this.#inflate = undefined;
+    this.#chunks = [];
+    this.#failure = undefined;
+    this.#pendingReject = undefined;
+    if (!inflate)
+      return;
+    inflate.removeAllListeners();
+    try {
+      inflate.close();
+    } catch {}
+  }
+  #awaiting(run) {
+    if (this.#failure)
+      return Promise.reject(this.#failure);
+    return new Promise((resolve, reject) => {
+      this.#pendingReject = reject;
+      run((error) => {
+        this.#pendingReject = undefined;
+        if (error)
+          reject(error);
+        else if (this.#failure)
+          reject(this.#failure);
+        else
+          resolve();
+      });
+    });
+  }
+  #open() {
+    const inflate = this.#create();
+    inflate.on("data", (chunk) => this.#chunks.push(chunk));
+    inflate.on("error", (error) => {
+      this.#failure = error;
+      const reject = this.#pendingReject;
+      this.#pendingReject = undefined;
+      reject?.(error);
+    });
+    return inflate;
+  }
+}
+function createDecoder(compress) {
+  return compress ? new ZlibStreamDecoder : new PlainTextDecoder;
+}
+
+// packages/ws/src/transport.ts
+var OPEN = 1;
+
+class WebSocketTransport {
+  #handlers;
+  #decoder;
+  #createSocket;
+  #compress;
+  #socket;
+  #generation = 0;
+  #queue = Promise.resolve();
+  constructor(options) {
+    this.#handlers = options.handlers;
+    this.#compress = options.compress ?? false;
+    this.#decoder = options.decoder ?? createDecoder(options.compress);
+    this.#createSocket = options.createSocket ?? ((url) => new WebSocket(url));
+  }
+  get connected() {
+    return this.#socket?.readyState === OPEN;
+  }
+  get live() {
+    return this.#socket !== undefined && this.#socket.readyState <= OPEN;
+  }
+  get generation() {
+    return this.#generation;
+  }
+  connect(url) {
+    this.#discard(1000, "Superseded by a new connection");
+    const generation = ++this.#generation;
+    this.#decoder.reset();
+    this.#queue = Promise.resolve();
+    let socket;
+    try {
+      socket = this.#createSocket(url);
+    } catch (error) {
+      return { ok: false, error: this.#asError(error) };
+    }
+    if (this.#compress) {
+      try {
+        socket.binaryType = "arraybuffer";
+      } catch {}
+    }
+    this.#socket = socket;
+    socket.addEventListener("open", () => {
+      if (!this.#owns(generation))
+        return;
+      this.#handlers.onOpen();
+    });
+    socket.addEventListener("message", (event) => {
+      if (!this.#owns(generation))
+        return;
+      let decoded;
+      try {
+        decoded = this.#decoder.push(event.data);
+      } catch (error) {
+        this.#handlers.onError(this.#asError(error));
+        return;
+      }
+      if (!(decoded instanceof Promise)) {
+        for (const frame of decoded)
+          this.#handlers.onFrame(frame);
+        return;
+      }
+      this.#queue = this.#queue.then(async () => {
+        const frames = await decoded;
+        if (!this.#owns(generation))
+          return;
+        for (const frame of frames)
+          this.#handlers.onFrame(frame);
+      }).catch((error) => {
+        if (!this.#owns(generation))
+          return;
+        this.#handlers.onError(this.#asError(error));
+      });
+    });
+    socket.addEventListener("close", (event) => {
+      if (!this.#owns(generation))
+        return;
+      this.#socket = undefined;
+      this.#generation++;
+      this.#decoder.reset();
+      this.#handlers.onClose(event.code, event.reason ?? "");
+    });
+    socket.addEventListener("error", () => {
+      if (!this.#owns(generation))
+        return;
+      this.#handlers.onError(new Error("Gateway WebSocket error"));
+    });
+    return { ok: true };
+  }
+  send(data) {
+    if (!this.connected)
+      return false;
+    try {
+      this.#socket.send(data);
+      return true;
+    } catch (error) {
+      this.#handlers.onError(this.#asError(error));
+      return false;
+    }
+  }
+  close(code = 1000, reason = "") {
+    const socket = this.#socket;
+    if (!socket)
+      return;
+    try {
+      socket.close(code, reason);
+    } catch (error) {
+      this.#handlers.onError(this.#asError(error));
+    }
+  }
+  destroy(code = 1000, reason = "") {
+    this.#discard(code, reason);
+    this.#decoder.reset();
+  }
+  #owns(generation) {
+    return generation === this.#generation;
+  }
+  #discard(code, reason) {
+    const socket = this.#socket;
+    if (!socket)
+      return;
+    this.#generation++;
+    this.#socket = undefined;
+    try {
+      socket.close(code, reason);
+    } catch (error) {
+      this.#handlers.onError(this.#asError(error));
+    }
+  }
+  #asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+}
+
+// packages/ws/src/opcodes.ts
+var GatewayOpcodes = {
+  Dispatch: 0,
+  Heartbeat: 1,
+  Identify: 2,
+  PresenceUpdate: 3,
+  VoiceStateUpdate: 4,
+  Resume: 6,
+  Reconnect: 7,
+  RequestGuildMembers: 8,
+  InvalidSession: 9,
+  Hello: 10,
+  HeartbeatAck: 11
+};
+
+// packages/ws/src/protocol.ts
+function classifyFrame(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch (error) {
+    return {
+      sequence: null,
+      action: {
+        type: "invalid",
+        violation: "invalid-json",
+        message: "Gateway returned invalid JSON",
+        cause: error
+      }
+    };
+  }
+  return classifyPayload(payload);
+}
+function classifyPayload(payload) {
+  if (payload === null || typeof payload !== "object" || typeof payload.op !== "number")
+    return {
+      sequence: null,
+      action: {
+        type: "invalid",
+        violation: "invalid-payload",
+        message: "Gateway returned an invalid payload"
+      }
+    };
+  const frame = payload;
+  const sequence = typeof frame.s === "number" ? frame.s : null;
+  switch (frame.op) {
+    case GatewayOpcodes.Dispatch:
+      return {
+        sequence,
+        action: {
+          type: "dispatch",
+          event: typeof frame.t === "string" ? frame.t : null,
+          data: frame.d
+        }
+      };
+    case GatewayOpcodes.Hello: {
+      const interval = frame.d?.heartbeat_interval;
+      if (typeof interval !== "number" || !Number.isFinite(interval) || interval <= 0)
+        return {
+          sequence,
+          action: {
+            type: "invalid",
+            violation: "invalid-hello",
+            message: "Gateway HELLO payload contains an invalid heartbeat interval"
+          }
+        };
+      return {
+        sequence,
+        action: { type: "hello", heartbeatInterval: interval }
+      };
+    }
+    case GatewayOpcodes.Heartbeat:
+      return { sequence, action: { type: "heartbeat" } };
+    case GatewayOpcodes.HeartbeatAck:
+      return {
+        sequence,
+        action: { type: "heartbeat-ack", data: frame.d }
+      };
+    case GatewayOpcodes.Reconnect:
+      return { sequence, action: { type: "reconnect" } };
+    case GatewayOpcodes.InvalidSession:
+      return {
+        sequence,
+        action: {
+          type: "invalid-session",
+          resumable: frame.d === true
+        }
+      };
+    default:
+      return { sequence, action: { type: "unknown", opcode: frame.op } };
+  }
+}
+function identifyPayload(options) {
+  const props = options.properties ?? {};
+  const os = props.os ?? "Android";
+  const browser = props.browser ?? "Discord Android";
+  const device = props.device ?? "Discord Android";
+  return {
+    op: GatewayOpcodes.Identify,
+    d: {
+      token: options.token,
+      intents: options.intents,
+      properties: {
+        os,
+        browser,
+        device,
+        $os: os,
+        $browser: browser,
+        $device: device,
+        ...props
+      },
+      presence: {
+        since: options.presence?.since ?? null,
+        activities: options.presence?.activities ?? [],
+        status: options.presence?.status ?? "online",
+        afk: Boolean(options.presence?.afk)
+      },
+      shard: [options.shardId, options.shardCount]
+    },
+    s: null,
+    t: null
+  };
+}
+function resumePayload(token, resume) {
+  return {
+    op: GatewayOpcodes.Resume,
+    d: {
+      token,
+      session_id: resume.sessionId,
+      seq: resume.sequence
+    },
+    s: null,
+    t: null
+  };
+}
+function heartbeatPayload(sequence) {
+  return { op: GatewayOpcodes.Heartbeat, d: sequence, s: null, t: null };
+}
+
+// packages/types/src/gateway.ts
 var GatewayIntentBits = {
   Guilds: 1 << 0,
   GuildMembers: 1 << 1,
@@ -54,6 +751,8 @@ var IntentBits = {
 function resolveGatewayIntents(intents) {
   if (typeof intents === "number")
     return intents;
+  if (intents && typeof intents === "object" && !Array.isArray(intents))
+    return intents.bitfield;
   if (Array.isArray(intents)) {
     return intents.reduce((acc, intent) => {
       return acc | resolveGatewayIntents(intent);
@@ -73,21 +772,7 @@ function resolveGatewayIntents(intents) {
   }
   return 0;
 }
-
-// packages/ws/src/index.ts
-var GatewayOpcodes = {
-  Dispatch: 0,
-  Heartbeat: 1,
-  Identify: 2,
-  PresenceUpdate: 3,
-  VoiceStateUpdate: 4,
-  Resume: 6,
-  Reconnect: 7,
-  RequestGuildMembers: 8,
-  InvalidSession: 9,
-  Hello: 10,
-  HeartbeatAck: 11
-};
+// packages/ws/src/state.ts
 class GatewayError extends Error {
   code;
   constructor(message, code, options) {
@@ -96,31 +781,43 @@ class GatewayError extends Error {
     this.code = code;
   }
 }
+// packages/ws/src/send-budget.ts
+class SendBudget {
+  #timestamps = [];
+  #limit;
+  #windowMs;
+  constructor(limit = 115, windowMs = 60000) {
+    this.#limit = limit;
+    this.#windowMs = windowMs;
+  }
+  get used() {
+    return this.#timestamps.length;
+  }
+  allows(privileged, now = Date.now()) {
+    while (this.#timestamps.length && now - this.#timestamps[0] >= this.#windowMs)
+      this.#timestamps.shift();
+    return privileged || this.#timestamps.length < this.#limit;
+  }
+  record(now = Date.now()) {
+    this.#timestamps.push(now);
+  }
+}
+
+// packages/ws/src/index.ts
+var DEFAULT_GATEWAY_URL = "wss://gateway.discord.gg/?v=10&encoding=json";
 
 class Gateway {
   state = "CONNECT" /* Connect */;
   #options;
-  #ws;
-  #sequence = null;
-  #sessionId;
-  #resumeURL;
-  #heartbeatTimer;
-  #initialHeartbeat;
-  #heartbeatAckTimer;
-  #heartbeatACK = true;
-  #heartbeatInterval = 0;
-  #heartbeatSentAt = 0;
-  #lastMessageAt = 0;
-  #zombieTimer;
-  #zombieReported = false;
+  #transport;
+  #session = new GatewaySession;
+  #token = 0;
+  #heartbeat;
   #closed = false;
-  #attempt = 0;
-  #reconnectTimer;
-  #connectPromise;
-  #resolveConnect;
-  #rejectConnect;
+  #reconnect;
   #listeners = new Map;
-  #sendTimestamps = [];
+  #sendBudget = new SendBudget;
+  ping = -1;
   constructor(options) {
     if (!options.token?.trim())
       throw new TypeError("A Gateway token is required.");
@@ -141,39 +838,78 @@ class Gateway {
         browser: "Discord Android",
         device: "Discord Android"
       },
-      presence: { status: "online", activities: [], afk: false, since: null },
-      ...options
+      presence: {
+        status: "online",
+        activities: [],
+        afk: false,
+        since: null
+      },
+      ...options,
+      intents: resolvedIntents
     };
     if (this.#options.shardId < 0 || this.#options.shardId >= this.#options.shardCount)
       throw new RangeError("Gateway shardId must be within the configured shard count.");
     if (this.#options.zombieTimeout <= this.#options.heartbeatAckTimeout)
       throw new RangeError("Gateway zombieTimeout must be greater than heartbeatAckTimeout");
+    this.#transport = new WebSocketTransport({
+      compress: this.#options.compress,
+      createSocket: options.createSocket,
+      handlers: {
+        onOpen: () => this.#onOpen(),
+        onFrame: (raw) => this.#message(raw, this.#token),
+        onClose: (code) => this.#close(code, this.#token),
+        onError: (error) => this.#emitError(error instanceof GatewayError ? error : new GatewayError(error.message, undefined, {
+          cause: error
+        }))
+      }
+    });
+    this.#reconnect = new GatewayReconnect({
+      enabled: this.#options.reconnect,
+      maxAttempts: this.#options.maxReconnectAttempts,
+      baseDelay: this.#options.reconnectBaseDelay,
+      maxDelay: this.#options.reconnectMaxDelay
+    });
+    this.#heartbeat = new GatewayHeartbeat({
+      ackTimeout: this.#options.heartbeatAckTimeout,
+      zombieTimeout: this.#options.zombieTimeout,
+      send: (sequence) => this.#dispatch(heartbeatPayload(sequence), true),
+      sequence: () => this.#session.sequence,
+      isConnected: () => !this.#closed && this.#transport.connected,
+      onTimeout: (timeout) => this.#onHeartbeatTimeout(timeout),
+      onError: (error) => this.#emitError(error)
+    });
   }
-  connect(url = "wss://gateway.discord.gg/?v=10&encoding=json") {
+  #onHeartbeatTimeout(timeout) {
+    if (timeout.type === "zombie") {
+      this.#emit("zombie", {
+        silentFor: timeout.silentFor,
+        timeout: timeout.deadline
+      });
+      this.#emitError(new GatewayError(`Gateway connection appears stale after ${timeout.silentFor}ms without traffic.`));
+    } else {
+      this.#emitError(new GatewayError(`Gateway heartbeat acknowledgement timed out after ${timeout.elapsedMs}ms.`));
+    }
+    this.#transport.close(1001, timeout.type === "zombie" ? "Zombie Gateway connection" : "Heartbeat timeout");
+  }
+  connect(url = DEFAULT_GATEWAY_URL) {
     if (this.state === "CLOSED" /* Closed */)
       throw new GatewayError("Gateway has been permanently closed.");
-    if (this.#connectPromise)
-      return this.#connectPromise;
+    const inFlight = this.#reconnect.attemptPromise;
+    if (inFlight)
+      return inFlight;
+    if (this.#transport.live)
+      return Promise.resolve();
+    this.#reconnect.cancel();
     this.#closed = false;
     this.#setState("CONNECT" /* Connect */);
-    this.#connectPromise = new Promise((resolve, reject) => {
-      this.#resolveConnect = resolve;
-      this.#rejectConnect = reject;
-      this.#open(url);
-    });
-    return this.#connectPromise;
+    const connectURL = this.#options.compress ? url.includes("compress=") ? url : `${url}&compress=zlib-stream` : url;
+    return this.#reconnect.attempt(() => this.#open(connectURL));
   }
   close() {
     this.#closed = true;
     this.#clearTimers();
     this.#settleConnect(new GatewayError("Gateway connection closed before socket open."));
-    const ws = this.#ws;
-    this.#ws = undefined;
-    try {
-      ws?.close(1000, "Client closed connection");
-    } catch (error) {
-      this.#emitError(error);
-    }
+    this.#transport.destroy(1000, "Client closed connection");
     this.#setState("CLOSED" /* Closed */);
   }
   emit(event, data) {
@@ -195,23 +931,20 @@ class Gateway {
   send(payload) {
     if (!payload || !Number.isInteger(payload.op))
       throw new TypeError("Gateway payload must contain an integer opcode.");
-    if (this.#ws?.readyState !== WebSocket.OPEN)
+    return this.#dispatch(payload, false);
+  }
+  #dispatch(payload, privileged) {
+    if (!this.#transport.connected)
       return false;
     const now = Date.now();
-    while (this.#sendTimestamps.length && now - this.#sendTimestamps[0] >= 60000)
-      this.#sendTimestamps.shift();
-    if (this.#sendTimestamps.length >= 115) {
+    if (!this.#sendBudget.allows(privileged, now)) {
       this.#emitError(new GatewayError("Gateway send rate budget exhausted."));
       return false;
     }
-    try {
-      this.#ws.send(JSON.stringify(payload));
-      this.#sendTimestamps.push(now);
-      return true;
-    } catch (error) {
-      this.#emitError(error);
+    if (!this.#transport.send(JSON.stringify(payload)))
       return false;
-    }
+    this.#sendBudget.record(now);
+    return true;
   }
   setPresence(data) {
     this.#options.presence = { ...this.#options.presence, ...data };
@@ -247,289 +980,142 @@ class Gateway {
   #open(url) {
     if (this.#closed)
       return;
-    let ws;
-    try {
-      ws = new WebSocket(url);
-    } catch (error) {
-      const failure = this.#normalizeError(error);
-      this.#emitError(failure);
-      if (this.#options.reconnect) {
-        this.#setState("RECONNECT" /* Reconnect */);
-        this.#scheduleReconnect();
-      } else
-        this.#settleConnect(failure);
+    this.#token = this.#session.beginConnection();
+    const result = this.#transport.connect(url);
+    if (result.ok)
       return;
+    const failure = this.#normalizeError(result.error);
+    this.#emitError(failure);
+    if (this.#options.reconnect) {
+      this.#setState("RECONNECT" /* Reconnect */);
+      this.#scheduleReconnect();
+    } else {
+      this.#settleConnect(failure);
     }
-    this.#ws = ws;
-    ws.addEventListener("open", () => {
-      this.#lastMessageAt = Date.now();
-      this.#zombieReported = false;
-      this.#startZombieDetection();
-      this.#emit("open", undefined);
-      this.#settleConnect();
-    });
-    ws.addEventListener("message", (event) => {
-      this.#lastMessageAt = Date.now();
-      this.#zombieReported = false;
-      this.#message(ws, String(event.data));
-    });
-    ws.addEventListener("close", (event) => this.#close(ws, event.code));
-    ws.addEventListener("error", () => this.#emitError(new GatewayError("Gateway WebSocket error")));
-  }
-  #startZombieDetection() {
-    if (this.#zombieTimer)
-      clearInterval(this.#zombieTimer);
-    const interval = Math.max(1, Math.min(250, this.#options.heartbeatAckTimeout, this.#options.zombieTimeout / 2));
-    this.#zombieTimer = setInterval(() => {
-      if (this.#closed || this.#ws?.readyState !== WebSocket.OPEN || this.#lastMessageAt === 0)
-        return;
-      const silentFor = Date.now() - this.#lastMessageAt;
-      const deadline = Math.max(this.#options.zombieTimeout, this.#heartbeatInterval + this.#options.heartbeatAckTimeout);
-      if (silentFor < deadline || this.#zombieReported)
-        return;
-      this.#zombieReported = true;
-      const error = new GatewayError(`Gateway connection appears stale after ${silentFor}ms without traffic.`);
-      this.#emit("zombie", { silentFor, timeout: deadline });
-      this.#emitError(error);
-      try {
-        this.#ws.close(1001, "Zombie Gateway connection");
-      } catch (closeError) {
-        this.#emitError(closeError);
-      }
-    }, interval);
   }
-  #message(ws, raw) {
-    let payload;
-    try {
-      payload = JSON.parse(raw);
-    } catch (error) {
-      this.#emitError(new GatewayError("Gateway returned invalid JSON", undefined, {
-        cause: error
-      }));
-      ws.close(1002, "Invalid JSON");
-      return;
-    }
-    if (!payload || typeof payload.op !== "number") {
-      this.#emitError(new GatewayError("Gateway returned an invalid payload"));
-      ws.close(1002, "Invalid payload");
+  #onOpen() {
+    this.#heartbeat.watch();
+    this.#emit("open", undefined);
+    this.#settleConnect();
+  }
+  #message(raw, token) {
+    if (!this.#session.owns(token))
       return;
-    }
-    if (typeof payload.s === "number")
-      this.#sequence = payload.s;
-    switch (payload.op) {
-      case GatewayOpcodes.Dispatch:
+    const { sequence, action } = classifyFrame(raw);
+    if (sequence !== null)
+      this.#session.recordSequence(sequence, token);
+    this.#apply(action, token);
+  }
+  #apply(action, token) {
+    switch (action.type) {
+      case "dispatch":
         this.#setState("DISPATCH" /* Dispatch */);
-        this.#handleDispatch(payload.t, payload.d);
-        break;
-      case GatewayOpcodes.Hello:
-        this.#handleHello(payload.d);
-        break;
-      case GatewayOpcodes.Heartbeat:
+        this.#handleDispatch(action.event, action.data, token);
+        return;
+      case "hello":
+        this.#handleHello(action.heartbeatInterval);
+        return;
+      case "heartbeat":
         this.#setState("HEARTBEAT" /* Heartbeat */);
-        this.#sendHeartbeat();
-        break;
-      case GatewayOpcodes.HeartbeatAck:
-        this.#heartbeatACK = true;
-        this.#clearHeartbeatAckTimer();
-        this.#emit("heartbeatAck", payload.d);
-        break;
-      case GatewayOpcodes.Reconnect:
-        ws.close(1001, "Server requested reconnect");
-        break;
-      case GatewayOpcodes.InvalidSession:
-        this.#sessionId = undefined;
-        this.#sequence = null;
-        this.#emit("invalidSession", payload.d);
-        ws.close(1000, "Invalid session");
-        break;
-    }
-  }
-  #handleDispatch(event, data) {
+        this.#heartbeat.sendHeartbeat();
+        return;
+      case "heartbeat-ack":
+        this.#heartbeat.acknowledge();
+        this.ping = this.#heartbeat.latency;
+        this.#emit("heartbeatAck", action.data);
+        return;
+      case "reconnect":
+        this.#transport.close(1001, "Server requested reconnect");
+        return;
+      case "invalid-session": {
+        if (!action.resumable)
+          this.#session.invalidate(token, "invalid-session");
+        this.#emit("invalidSession", action.resumable);
+        this.#transport.close(action.resumable ? GatewayCloseCodes.UnknownError : 1000, action.resumable ? "Invalid session (resumable)" : "Invalid session");
+        return;
+      }
+      case "invalid":
+        this.#emitError(new GatewayError(action.message, undefined, action.cause === undefined ? undefined : { cause: action.cause }));
+        this.#transport.close(1002, action.violation === "invalid-json" ? "Invalid JSON" : action.violation === "invalid-hello" ? "Invalid heartbeat interval" : "Invalid payload");
+        return;
+      case "unknown":
+        return;
+    }
+  }
+  #handleDispatch(event, data, token) {
     if (event === "READY") {
-      const ready = data;
-      if (typeof ready?.session_id !== "string" || typeof ready?.resume_gateway_url !== "string") {
-        this.#emitError(new GatewayError("Gateway READY payload is missing session information"));
+      if (!this.#session.activate(data, token)) {
+        if (this.#session.owns(token))
+          this.#emitError(new GatewayError("Gateway READY payload is missing session information"));
         return;
       }
-      this.#sessionId = ready.session_id;
-      this.#resumeURL = ready.resume_gateway_url;
-      this.#attempt = 0;
+      this.#reconnect.reset();
       this.#setState("READY" /* Ready */);
       this.#emit("ready", data);
+    } else if (event === "RESUMED") {
+      this.#reconnect.reset();
+      this.#setState("READY" /* Ready */);
+      this.#emit("resumed", data);
     }
     this.#emit("RAW", { event: event ?? "UNKNOWN", data });
     if (this.#closed)
       return;
     this.#emit(event ?? "dispatch", data);
   }
-  #handleHello(data) {
-    const interval = data?.heartbeat_interval;
-    if (typeof interval !== "number" || !Number.isFinite(interval) || interval <= 0) {
-      this.#emitError(new GatewayError("Gateway HELLO payload contains an invalid heartbeat interval"));
-      this.#ws?.close(1002, "Invalid heartbeat interval");
-      return;
-    }
-    this.#heartbeatInterval = interval;
-    this.#setState(this.#sessionId && this.#sequence !== null && this.#resumeURL ? "RESUME" /* Resume */ : "HELLO" /* Hello */);
-    this.#startHeartbeat(interval);
+  #handleHello(interval) {
+    this.#setState(this.#session.canResume ? "RESUME" /* Resume */ : "HELLO" /* Hello */);
+    this.#heartbeat.start(interval);
     this.#identifyOrResume();
   }
   #identifyOrResume() {
-    if (this.#sessionId && this.#sequence !== null && this.#resumeURL) {
+    const intent = this.#session.handshake();
+    if (intent.type === "resume") {
       this.#setState("RESUME" /* Resume */);
-      this.send({
-        op: GatewayOpcodes.Resume,
-        d: {
-          token: this.#options.token,
-          session_id: this.#sessionId,
-          seq: this.#sequence
-        },
-        s: null,
-        t: null
-      });
+      this.#dispatch(resumePayload(this.#options.token, intent), true);
       return;
     }
     this.#setState("IDENTIFY" /* Identify */);
-    const props = this.#options.properties ?? {
-      os: "Android",
-      browser: "Discord Android",
-      device: "Discord Android"
-    };
-    const os = props.os ?? "Android";
-    const browser = props.browser ?? "Discord Android";
-    const device = props.device ?? "Discord Android";
-    this.send({
-      op: GatewayOpcodes.Identify,
-      d: {
-        token: this.#options.token,
-        intents: this.#options.intents,
-        properties: {
-          os,
-          browser,
-          device,
-          $os: os,
-          $browser: browser,
-          $device: device,
-          ...props
-        },
-        presence: {
-          since: this.#options.presence?.since ?? null,
-          activities: this.#options.presence?.activities ?? [],
-          status: this.#options.presence?.status ?? "online",
-          afk: Boolean(this.#options.presence?.afk)
-        },
-        shard: [this.#options.shardId, this.#options.shardCount]
-      },
-      s: null,
-      t: null
-    });
-  }
-  #startHeartbeat(interval) {
-    this.#clearHeartbeatTimers();
-    this.#heartbeatACK = true;
-    this.#initialHeartbeat = setTimeout(() => this.#sendHeartbeat(), Math.random() * interval);
-    this.#heartbeatTimer = setInterval(() => this.#sendHeartbeat(), interval);
-  }
-  #sendHeartbeat() {
-    this.#heartbeatACK = false;
-    this.#heartbeatSentAt = Date.now();
-    if (!this.send({
-      op: GatewayOpcodes.Heartbeat,
-      d: this.#sequence,
-      s: null,
-      t: null
-    })) {
-      this.#emitError(new GatewayError("Unable to send Gateway heartbeat because the WebSocket is not open."));
-      return;
-    }
-    this.#clearHeartbeatAckTimer();
-    this.#heartbeatAckTimer = setTimeout(() => {
-      if (!this.#heartbeatACK) {
-        const elapsed = Date.now() - this.#heartbeatSentAt;
-        this.#emitError(new GatewayError(`Gateway heartbeat acknowledgement timed out after ${elapsed}ms.`));
-        try {
-          this.#ws?.close(1001, "Heartbeat timeout");
-        } catch (error) {
-          this.#emitError(error);
-        }
-      }
-    }, this.#options.heartbeatAckTimeout);
+    this.#dispatch(identifyPayload({
+      token: this.#options.token,
+      intents: this.#options.intents,
+      shardId: this.#options.shardId,
+      shardCount: this.#options.shardCount,
+      properties: this.#options.properties,
+      presence: this.#options.presence
+    }), true);
   }
-  #close(ws, code) {
-    if (this.#ws !== ws)
-      return;
-    this.#ws = undefined;
+  #close(code, token) {
     this.#clearTimers();
-    const action = this.#closeAction(code);
+    const action = this.#reconnect.classifyClose(code, this.#session.canResume);
     this.#emit("close", { code, action });
-    if (this.#closed || !this.#options.reconnect || action === "stop") {
+    if (this.#closed || !this.#reconnect.enabled || action === "stop") {
+      if (action === "stop")
+        this.#closed = true;
       this.#setState(this.#closed ? "CLOSED" /* Closed */ : "CONNECT" /* Connect */);
-      if (this.#connectPromise)
-        this.#settleConnect(new GatewayError(`Gateway closed before READY (code ${code}).`, code));
+      if (this.#reconnect.connecting)
+        this.#reconnect.settle(new GatewayError(`Gateway closed before READY (code ${code}).`, code));
       return;
     }
-    if (action === "identify") {
-      this.#sequence = null;
-      this.#sessionId = undefined;
-    }
+    if (action === "identify")
+      this.#session.invalidate(token, "session-timeout");
     this.#setState("RECONNECT" /* Reconnect */);
     this.#scheduleReconnect();
   }
-  #closeAction(code) {
-    if ([4004, 4010, 4011, 4012, 4013, 4014].includes(code))
-      return "stop";
-    if ([4007, 4009].includes(code))
-      return "identify";
-    return this.#sessionId && this.#sequence !== null ? "resume" : "identify";
-  }
   #scheduleReconnect() {
-    if (this.#closed || !this.#options.reconnect || this.#reconnectTimer)
+    if (this.#closed)
       return;
-    if (this.#attempt >= this.#options.maxReconnectAttempts) {
-      this.#settleConnect(new GatewayError("Gateway reconnect attempts exhausted."));
-      this.#setState("CONNECT" /* Connect */);
+    const result = this.#reconnect.schedule(() => this.#open(this.#session.connectURL(DEFAULT_GATEWAY_URL)));
+    if (result.scheduled || result.reason !== "exhausted")
       return;
-    }
-    const delay = Math.min(this.#options.reconnectMaxDelay, this.#options.reconnectBaseDelay * 2 ** this.#attempt++);
-    const jitter = Math.random() * Math.min(250, Math.max(1, delay * 0.25));
-    this.#reconnectTimer = setTimeout(() => {
-      this.#reconnectTimer = undefined;
-      this.#open(this.#resumeURL ?? "wss://gateway.discord.gg/?v=10&encoding=json");
-    }, delay + jitter);
+    this.#reconnect.settle(new GatewayError("Gateway reconnect attempts exhausted."));
+    this.#setState("CONNECT" /* Connect */);
   }
   #settleConnect(error) {
-    const resolve = this.#resolveConnect;
-    const reject = this.#rejectConnect;
-    this.#resolveConnect = undefined;
-    this.#rejectConnect = undefined;
-    this.#connectPromise = undefined;
-    if (error)
-      reject?.(error);
-    else
-      resolve?.();
-  }
-  #clearHeartbeatAckTimer() {
-    if (this.#heartbeatAckTimer)
-      clearTimeout(this.#heartbeatAckTimer);
-    this.#heartbeatAckTimer = undefined;
-  }
-  #clearHeartbeatTimers() {
-    if (this.#heartbeatTimer)
-      clearInterval(this.#heartbeatTimer);
-    if (this.#initialHeartbeat)
-      clearTimeout(this.#initialHeartbeat);
-    this.#clearHeartbeatAckTimer();
-    this.#heartbeatTimer = undefined;
-    this.#initialHeartbeat = undefined;
+    this.#reconnect.settle(error);
   }
   #clearTimers() {
-    if (this.#reconnectTimer)
-      clearTimeout(this.#reconnectTimer);
-    if (this.#zombieTimer)
-      clearInterval(this.#zombieTimer);
-    this.#reconnectTimer = undefined;
-    this.#zombieTimer = undefined;
-    this.#clearHeartbeatTimers();
+    this.#reconnect.cancel();
+    this.#heartbeat.stop();
   }
   #normalizeError(error) {
     return error instanceof GatewayError ? error : new GatewayError("Gateway connection failed.", undefined, {
@@ -564,13 +1150,17 @@ class Gateway {
 }
 
 // packages/sharding/src/bus.ts
+var REPLY_TYPE = "__lunibee:reply";
+
 class ShardBus {
   #channel;
   #handlers = new Map;
+  #errorHandlers = new Set;
   #shardId;
   #namespace;
   channelName;
   #counter = 0;
+  #pending = new Map;
   constructor(shardId, channelName) {
     if (!Number.isInteger(shardId) || shardId < 0)
       throw new RangeError("Shard ID must be a non-negative integer.");
@@ -595,6 +1185,16 @@ class ShardBus {
     this.#handlers.get(type)?.delete(handler);
     return this;
   }
+  onError(handler) {
+    if (typeof handler !== "function")
+      throw new TypeError("Shard bus error handler is required.");
+    this.#errorHandlers.add(handler);
+    return this;
+  }
+  offError(handler) {
+    this.#errorHandlers.delete(handler);
+    return this;
+  }
   send(target, type, data) {
     if (!Number.isInteger(target) || target < 0)
       throw new RangeError("Shard target must be a non-negative integer.");
@@ -603,11 +1203,56 @@ class ShardBus {
   broadcast(type, data) {
     return this.#publish(null, type, data);
   }
+  respond(type, handler) {
+    return this.on(type, async (message) => {
+      if (!message.expectsReply)
+        return;
+      const reply = { requestId: message.id };
+      try {
+        reply.result = await handler(message.data, message);
+      } catch (error) {
+        reply.error = error instanceof Error ? error.message : String(error);
+      }
+      this.#publish(message.source, REPLY_TYPE, reply);
+    });
+  }
+  async request(target, type, data, timeoutMs = 5000) {
+    if (!Number.isInteger(target) || target < 0)
+      throw new RangeError("Shard target must be a non-negative integer.");
+    const [reply] = await this.#collect(target, type, data, timeoutMs, 1);
+    if (!reply)
+      throw new Error(`Shard ${target} did not reply to "${type}" within ${timeoutMs}ms.`);
+    if (reply.error !== undefined)
+      throw new Error(reply.error);
+    return reply.result;
+  }
+  broadcastRequest(type, data, options = {}) {
+    return this.#collect(null, type, data, options.timeoutMs ?? 5000, options.expected ?? Number.POSITIVE_INFINITY);
+  }
+  #collect(target, type, data, timeoutMs, expected) {
+    const replies = [];
+    return new Promise((resolve) => {
+      let requestId = "";
+      const finish = () => {
+        clearTimeout(timer);
+        this.#pending.delete(requestId);
+        resolve(replies);
+      };
+      const timer = setTimeout(finish, timeoutMs);
+      requestId = this.#publish(target, type, data, true);
+      this.#pending.set(requestId, (reply) => {
+        replies.push(reply);
+        if (replies.length >= expected)
+          finish();
+      });
+    });
+  }
   close() {
     this.#channel.close();
     this.#handlers.clear();
+    this.#errorHandlers.clear();
   }
-  #publish(target, type, data) {
+  #publish(target, type, data, expectsReply = false) {
     if (!type.trim())
       throw new TypeError("Shard message type is required.");
     const id = `${this.#namespace}:${this.#shardId}:${++this.#counter}`;
@@ -616,7 +1261,8 @@ class ShardBus {
       target,
       type,
       data,
-      id
+      id,
+      ...expectsReply ? { expectsReply } : {}
     });
     return id;
   }
@@ -625,20 +1271,215 @@ class ShardBus {
       return;
     if (message.source === this.#shardId || message.target !== null && message.target !== this.#shardId)
       return;
+    if (message.type === REPLY_TYPE) {
+      const reply = message.data;
+      this.#pending.get(reply?.requestId)?.({
+        shardId: message.source,
+        ...reply.error !== undefined ? { error: reply.error } : { result: reply.result }
+      });
+      return;
+    }
     for (const handler of this.#handlers.get(message.type) ?? []) {
       try {
         const result = handler(message);
         if (result && typeof result.then === "function")
-          Promise.resolve(result).catch(() => {
-            return;
-          });
+          Promise.resolve(result).catch((error) => this.#reportError(error, message));
+      } catch (error) {
+        this.#reportError(error, message);
+      }
+    }
+  }
+  #reportError(error, message) {
+    for (const handler of this.#errorHandlers) {
+      try {
+        handler(error, message);
+      } catch {}
+    }
+  }
+}
+// packages/sharding/src/cluster.ts
+import { fork } from "child_process";
+import { cpus } from "os";
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+class ClusterManager {
+  clusters = new Map;
+  shardCount = 0;
+  #options;
+  #auto;
+  #autoScaleTimer;
+  #spawned = false;
+  #stopping = false;
+  #restartTimers = new Set;
+  constructor(options) {
+    if (!options.token?.trim())
+      throw new TypeError("A Discord bot token is required.");
+    if (!options.script?.trim())
+      throw new TypeError("A script path is required for clustering.");
+    if (options.autoScaleInterval !== undefined && (!Number.isInteger(options.autoScaleInterval) || options.autoScaleInterval < 1000)) {
+      throw new RangeError("autoScaleInterval must be an integer of at least 1000 milliseconds.");
+    }
+    this.#auto = options.shardCount === "auto";
+    this.#options = { ...options };
+  }
+  async fetchRecommendedShardCount() {
+    const response = await fetch("https://discord.com/api/v10/gateway/bot", {
+      headers: {
+        Authorization: `Bot ${this.#options.token}`,
+        "User-Agent": "Lunibee/0.1.0"
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`Gateway discovery failed with status ${response.status}`);
+    }
+    const data = await response.json();
+    if (typeof data.shards !== "number" || !Number.isInteger(data.shards) || data.shards < 1) {
+      throw new Error("Gateway discovery returned an invalid shard count.");
+    }
+    return data.shards;
+  }
+  async spawn() {
+    if (this.#spawned)
+      return;
+    if (typeof process?.versions?.bun === "string") {
+      throw new Error("ClusterManager requires the Node.js runtime; Bun does not support child_process.fork() for this clustering mode.");
+    }
+    this.#spawned = true;
+    const count = this.#options.shardCount === "auto" || this.#options.shardCount === undefined ? await this.fetchRecommendedShardCount() : this.#options.shardCount;
+    this.shardCount = count;
+    const clusterCount = this.#options.clusterCount ?? cpus().length;
+    const chunks = Array.from({ length: clusterCount }, () => []);
+    for (let i = 0;i < count; i++) {
+      chunks[i % clusterCount].push(i);
+    }
+    for (let i = 0;i < clusterCount; i++) {
+      if (chunks[i].length === 0)
+        continue;
+      this.#launch(i, chunks[i], count);
+      await sleep(500);
+    }
+    if (this.#options.autoScaleInterval && this.#options.autoScaleInterval > 0) {
+      this.#autoScaleTimer = setInterval(() => {
+        this.checkAutoScale();
+      }, this.#options.autoScaleInterval);
+    }
+  }
+  #launch(id, shards, shardCount) {
+    const child = fork(this.#options.script, [], {
+      env: {
+        ...process.env,
+        SHARD_LIST: shards.join(","),
+        SHARD_COUNT: shardCount.toString(),
+        CLUSTER_ID: id.toString()
+      }
+    });
+    const info = { id, process: child, shards };
+    this.clusters.set(id, info);
+    child.once("exit", (code, signal) => {
+      if (this.clusters.get(id)?.process !== child)
+        return;
+      try {
+        this.#options.onClusterExit?.(info, code, signal);
       } catch {}
+      if (this.#stopping || this.#options.restartOnExit === false)
+        return;
+      this.clusters.delete(id);
+      const timer = setTimeout(() => {
+        this.#restartTimers.delete(timer);
+        if (this.#stopping || !this.#spawned)
+          return;
+        this.#launch(id, shards, shardCount);
+      }, this.#options.restartDelay ?? 5000);
+      timer.unref?.();
+      this.#restartTimers.add(timer);
+    });
+    return info;
+  }
+  async checkAutoScale() {
+    if (!this.#auto)
+      return;
+    try {
+      const recommended = await this.fetchRecommendedShardCount();
+      if (recommended !== this.shardCount) {
+        await this.respawn(recommended);
+      }
+    } catch (error) {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      this.#options.onAutoScaleError?.(normalized);
+    }
+  }
+  async respawn(newShardCount) {
+    this.#options.shardCount = newShardCount;
+    await this.shutdownAll();
+    this.#spawned = false;
+    await this.spawn();
+  }
+  async shutdownAll(timeoutMs = this.#options.shutdownTimeout ?? 5000) {
+    this.#stopping = true;
+    this.#clearRestartTimers();
+    if (this.#autoScaleTimer) {
+      clearInterval(this.#autoScaleTimer);
+      this.#autoScaleTimer = undefined;
     }
+    await Promise.all([...this.clusters.values()].map((cluster) => this.#shutdownCluster(cluster, timeoutMs)));
+    this.clusters.clear();
+    this.#spawned = false;
+    this.#stopping = false;
+  }
+  #clearRestartTimers() {
+    for (const timer of this.#restartTimers)
+      clearTimeout(timer);
+    this.#restartTimers.clear();
+  }
+  async#shutdownCluster(cluster, timeoutMs) {
+    const child = cluster.process;
+    if (child.exitCode !== null || child.signalCode !== null)
+      return;
+    await new Promise((resolve) => {
+      let timer;
+      const finish = () => {
+        if (timer)
+          clearTimeout(timer);
+        resolve();
+      };
+      child.once("exit", finish);
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        child.off("exit", finish);
+        finish();
+        return;
+      }
+      timer = setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {}
+      }, timeoutMs);
+    });
+  }
+  killAll() {
+    this.#stopping = true;
+    this.#clearRestartTimers();
+    if (this.#autoScaleTimer) {
+      clearInterval(this.#autoScaleTimer);
+      this.#autoScaleTimer = undefined;
+    }
+    for (const cluster of this.clusters.values()) {
+      try {
+        cluster.process.kill();
+      } catch {}
+    }
+    this.clusters.clear();
+    this.#spawned = false;
+    this.#stopping = false;
   }
 }
 
 // packages/sharding/src/index.ts
+var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
 class ShardManager {
+  static IDENTIFY_INTERVAL = 5000;
   shards = new Map;
   get shardCount() {
     return this.shards.size;
@@ -646,6 +1487,8 @@ class ShardManager {
   #options;
   #resolved = false;
   #destroyed = false;
+  #auto;
+  #autoScaleTimer;
   constructor(options) {
     if (!options.token?.trim())
       throw new TypeError("A Discord bot token is required.");
@@ -654,7 +1497,15 @@ class ShardManager {
     const count = options.shardCount === "auto" || options.shardCount === undefined ? 1 : options.shardCount;
     if (!Number.isInteger(count) || count < 1)
       throw new RangeError("Shard count must be a positive integer.");
-    this.#options = { ...options };
+    if (options.autoScaleInterval !== undefined && (!Number.isInteger(options.autoScaleInterval) || options.autoScaleInterval < 1000))
+      throw new RangeError("autoScaleInterval must be an integer of at least 1000 milliseconds.");
+    if (options.spawnDelay !== undefined && (!Number.isFinite(options.spawnDelay) || options.spawnDelay < 0))
+      throw new RangeError("spawnDelay must be a non-negative finite number of milliseconds.");
+    this.#auto = options.shardCount === "auto";
+    this.#options = {
+      spawnDelay: ShardManager.IDENTIFY_INTERVAL,
+      ...options
+    };
     if (options.shardCount !== "auto")
       this.#initialize(count);
   }
@@ -673,24 +1524,56 @@ class ShardManager {
     return data.shards;
   }
   async connect() {
+    if (this.#autoScaleTimer) {
+      clearInterval(this.#autoScaleTimer);
+      this.#autoScaleTimer = undefined;
+    }
     await this.#ensureInitialized();
     for (const [id, shard] of this.shards) {
       try {
         await shard.connect();
       } catch (error) {
         this.destroy();
-        throw new Error(`Failed to connect shard ${id}.`, { cause: error });
+        throw new Error(`Failed to connect shard ${id}.`, {
+          cause: error
+        });
       }
       if (id + 1 < this.shardCount && this.#options.spawnDelay && this.#options.spawnDelay > 0)
-        await Bun.sleep(this.#options.spawnDelay);
+        await sleep2(this.#options.spawnDelay);
+    }
+    if (this.#options.autoScaleInterval && !this.#autoScaleTimer) {
+      this.#autoScaleTimer = setInterval(() => {
+        this.checkAutoScale();
+      }, this.#options.autoScaleInterval);
+    }
+  }
+  async checkAutoScale() {
+    if (!this.#auto)
+      return;
+    try {
+      const recommended = await this.fetchRecommendedShardCount();
+      if (recommended !== this.shardCount) {
+        await this.reshard(recommended);
+      }
+    } catch (error) {
+      this.#options.onAutoScaleError?.(error);
     }
   }
+  async reshard(count) {
+    this.#options.shardCount = count;
+    this.destroy();
+    await this.connect();
+  }
   destroy() {
     for (const shard of this.shards.values())
       shard.close();
     this.shards.clear();
     this.#resolved = false;
     this.#destroyed = true;
+    if (this.#autoScaleTimer) {
+      clearInterval(this.#autoScaleTimer);
+      this.#autoScaleTimer = undefined;
+    }
   }
   getShardIdForGuild(guildId) {
     const id = BigInt(guildId);
@@ -728,8 +1611,10 @@ class ShardManager {
   }
 }
 export {
+  ClusterManager,
   ShardBus,
-  ShardManager
+  ShardManager,
+  ShardManager as ShardingManager
 };
 
-//# debugId=155A3557E58FD4CF64756E2164756E21
+//# debugId=C1062D33C7999C8E64756E2164756E21