kimaki 0.4.78 → 0.4.80

package/dist/discord-bot.js

@@ -1,15 +1,16 @@
 // Core Discord bot module that handles message events and bot lifecycle.
 // Bridges Discord messages to OpenCode sessions, manages voice connections,
 // and orchestrates the main event loop for the Kimaki bot.
-import { initDatabase, closeDatabase, getThreadWorktree, createPendingWorktree, setWorktreeReady, setWorktreeError, getChannelWorktreesEnabled, getChannelMentionMode, getChannelDirectory, getPrisma, cancelAllPendingIpcRequests, } from './database.js';
+import { initDatabase, closeDatabase, getThreadWorktree, getThreadSession, createPendingWorktree, setWorktreeReady, setWorktreeError, getChannelWorktreesEnabled, getChannelMentionMode, getChannelDirectory, getPrisma, cancelAllPendingIpcRequests, } from './database.js';
 import { stopOpencodeServer, } from './opencode.js';
 import { formatWorktreeName } from './commands/new-worktree.js';
 import { WORKTREE_PREFIX } from './commands/merge-worktree.js';
 import { createWorktreeWithSubmodules } from './worktrees.js';
-import { escapeBackticksInCodeBlocks, splitMarkdownForDiscord, sendThreadMessage, SILENT_MESSAGE_FLAGS, reactToThread, stripMentions, hasKimakiBotPermission, hasNoKimakiRole, } from './discord-utils.js';
+import { escapeBackticksInCodeBlocks, splitMarkdownForDiscord, sendThreadMessage, SILENT_MESSAGE_FLAGS, NOTIFY_MESSAGE_FLAGS, reactToThread, stripMentions, hasKimakiBotPermission, hasNoKimakiRole, } from './discord-utils.js';
 import { getOpencodeSystemMessage, } from './system-message.js';
 import yaml from 'js-yaml';
 import { getTextAttachments, resolveMentions, } from './message-formatting.js';
+import { isVoiceAttachment } from './voice-attachment.js';
 import { preprocessExistingThreadMessage, preprocessNewThreadMessage, } from './message-preprocessing.js';
 import { cancelPendingActionButtons } from './commands/action-buttons.js';
 import { cancelPendingQuestion } from './commands/ask-question.js';
@@ -23,7 +24,7 @@ import { getOrCreateRuntime, disposeRuntime, } from './session-handler/thread-se
 import { runShellCommand } from './commands/run-command.js';
 import { registerInteractionHandler } from './interaction-handler.js';
 import { getDiscordRestApiUrl } from './discord-urls.js';
-import { stopHranaServer } from './hrana-server.js';
+import { markDiscordGatewayReady, stopHranaServer } from './hrana-server.js';
 import { notifyError } from './sentry.js';
 import { flushDebouncedProcessCallbacks } from './debounced-process-flush.js';
 import { startRuntimeIdleSweeper } from './runtime-idle-sweeper.js';
@@ -158,6 +159,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
             discordLogger.log(`Bot Application ID (provided): ${currentAppId}`);
         }
         voiceLogger.log('[READY] Bot is ready');
+        markDiscordGatewayReady();
         registerInteractionHandler({ discordClient: c, appId: currentAppId });
         registerVoiceStateHandler({ discordClient: c, appId: currentAppId });
         // Channel logging is informational only; do it in background so startup stays responsive.
@@ -173,7 +175,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                 discordLogger.log('  No channels for this bot');
             }
         })().catch((error) => {
-            discordLogger.warn(`Background guild channel scan failed: ${error instanceof Error ? error.message : String(error)}`);
+            discordLogger.warn(`Background guild channel scan failed: ${error instanceof Error ? error.stack : String(error)}`);
         });
     };
     // If client is already ready (was logged in before being passed to us),
@@ -258,6 +260,9 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
             const cliInjectedModel = isCliInjectedPrompt
                 ? promptMarker?.model
                 : undefined;
+            const cliInjectedPermissions = isCliInjectedPrompt
+                ? promptMarker?.permissions
+                : undefined;
             // Always ignore our own messages (unless CLI-injected prompt above).
             // Without this, assigning the Kimaki role to the bot itself would loop.
             if (isSelfBotMessage && !isCliInjectedPrompt) {
@@ -331,6 +336,15 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
             if (isThread) {
                 const thread = channel;
                 discordLogger.log(`Message in thread ${thread.name} (${thread.id})`);
+                // Only respond in threads kimaki knows about (has a session row in DB)
+                // or where the bot is explicitly @mentioned. This prevents the bot from
+                // hijacking user-created threads in project channels. (GitHub #84)
+                const hasExistingSession = await getThreadSession(thread.id);
+                const botMentioned = discordClient.user && message.mentions.has(discordClient.user.id);
+                if (!hasExistingSession && !botMentioned && !isCliInjectedPrompt) {
+                    discordLogger.log(`Ignoring thread ${thread.id}: no existing session and bot not mentioned`);
+                    return;
+                }
                 const parent = thread.parent;
                 let projectDirectory;
                 if (parent) {
@@ -352,7 +366,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                     if (worktreeInfo.status === 'error') {
                         await message.reply({
                             content: `❌ Worktree creation failed: ${(worktreeInfo.error_message || '').slice(0, 1900)}`,
-                            flags: SILENT_MESSAGE_FLAGS,
+                            flags: NOTIFY_MESSAGE_FLAGS,
                         });
                         return;
                     }
@@ -367,7 +381,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                     discordLogger.error(`Directory does not exist: ${projectDirectory}`);
                     await message.reply({
                         content: `✗ Directory does not exist: ${JSON.stringify(projectDirectory).slice(0, 1900)}`,
-                        flags: SILENT_MESSAGE_FLAGS,
+                        flags: NOTIFY_MESSAGE_FLAGS,
                     });
                     return;
                 }
@@ -391,8 +405,8 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                         return;
                     }
                 }
-                const hasVoiceAttachment = message.attachments.some((a) => {
-                    return a.contentType?.startsWith('audio/');
+                const hasVoiceAttachment = message.attachments.some((attachment) => {
+                    return isVoiceAttachment(attachment);
                 });
                 if (!projectDirectory) {
                     discordLogger.log(`Cannot process message: no project directory for thread ${thread.id}`);
@@ -442,6 +456,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                     appId: currentAppId,
                     agent: cliInjectedAgent,
                     model: cliInjectedModel,
+                    permissions: cliInjectedPermissions,
                     sessionStartSource: sessionStartSource
                         ? {
                             scheduleKind: sessionStartSource.scheduleKind,
@@ -492,7 +507,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                     discordLogger.error(`Directory does not exist: ${projectDirectory}`);
                     await message.reply({
                         content: `✗ Directory does not exist: ${JSON.stringify(projectDirectory).slice(0, 1900)}`,
-                        flags: SILENT_MESSAGE_FLAGS,
+                        flags: NOTIFY_MESSAGE_FLAGS,
                     });
                     return;
                 }
@@ -511,7 +526,9 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                         return;
                     }
                 }
-                const hasVoice = message.attachments.some((a) => a.contentType?.startsWith('audio/'));
+                const hasVoice = message.attachments.some((attachment) => {
+                    return isVoiceAttachment(attachment);
+                });
                 const baseThreadName = hasVoice
                     ? 'Voice Message'
                     : stripMentions(message.content || '')
@@ -555,7 +572,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                         });
                         await thread.send({
                             content: `⚠️ Failed to create worktree: ${errMsg}\nUsing main project directory instead.`,
-                            flags: SILENT_MESSAGE_FLAGS,
+                            flags: NOTIFY_MESSAGE_FLAGS,
                         });
                     }
                     else {
@@ -609,7 +626,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                 const errMsg = (error instanceof Error ? error.message : String(error)).slice(0, 1900);
                 await message.reply({
                     content: `Error: ${errMsg}`,
-                    flags: SILENT_MESSAGE_FLAGS,
+                    flags: NOTIFY_MESSAGE_FLAGS,
                 });
             }
             catch (sendError) {
@@ -633,7 +650,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
             const starterMessage = await thread
                 .fetchStarterMessage()
                 .catch((error) => {
-                discordLogger.warn(`[THREAD_CREATE] Failed to fetch starter message for thread ${thread.id}:`, error instanceof Error ? error.message : String(error));
+                discordLogger.warn(`[THREAD_CREATE] Failed to fetch starter message for thread ${thread.id}:`, error instanceof Error ? error.stack : String(error));
                 return null;
             });
             if (!starterMessage) {
@@ -675,7 +692,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                 discordLogger.error(`[BOT_SESSION] Directory does not exist: ${projectDirectory}`);
                 await thread.send({
                     content: `✗ Directory does not exist: ${JSON.stringify(projectDirectory).slice(0, 1900)}`,
-                    flags: SILENT_MESSAGE_FLAGS,
+                    flags: NOTIFY_MESSAGE_FLAGS,
                 });
                 return;
             }
@@ -710,11 +727,11 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                     });
                     await (worktreeStatusMessage?.edit({
                         content: `⚠️ Failed to create worktree: ${worktreeResult.message}\nUsing main project directory instead.`,
-                        flags: SILENT_MESSAGE_FLAGS,
+                        flags: NOTIFY_MESSAGE_FLAGS,
                     }) ||
                         thread.send({
                             content: `⚠️ Failed to create worktree: ${worktreeResult.message}\nUsing main project directory instead.`,
-                            flags: SILENT_MESSAGE_FLAGS,
+                            flags: NOTIFY_MESSAGE_FLAGS,
                         }));
                     return projectDirectory;
                 }
@@ -757,6 +774,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                 appId: currentAppId,
                 agent: marker.agent,
                 model: marker.model,
+                permissions: marker.permissions,
                 mode: 'opencode',
                 sessionStartSource: botThreadStartSource
                     ? {
@@ -773,7 +791,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
                 const errMsg = (error instanceof Error ? error.message : String(error)).slice(0, 1900);
                 await thread.send({
                     content: `Error: ${errMsg}`,
-                    flags: SILENT_MESSAGE_FLAGS,
+                    flags: NOTIFY_MESSAGE_FLAGS,
                 });
             }
             catch (sendError) {
@@ -786,7 +804,12 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
     discordClient.on(Events.ThreadDelete, (thread) => {
         disposeRuntime(thread.id);
     });
-    await discordClient.login(token);
+    // Skip login if the caller already connected the client (e.g. cli.ts logs in
+    // before calling startDiscordBot). Calling login() again destroys the existing
+    // WebSocket (close code 1000) and triggers a spurious ShardReconnecting event.
+    if (!discordClient.isReady()) {
+        await discordClient.login(token);
+    }
     startHeapMonitor();
     const stopTaskRunner = startTaskRunner({ token });
     const stopRuntimeIdleSweeper = startRuntimeIdleSweeper();
@@ -802,7 +825,7 @@ export async function startDiscordBot({ token, appId, discordClient, useWorktree
             await stopRuntimeIdleSweeper();
             await stopTaskRunner();
             await flushDebouncedProcessCallbacks().catch((error) => {
-                discordLogger.warn('Failed to flush debounced process callbacks:', error instanceof Error ? error.message : String(error));
+                discordLogger.warn('Failed to flush debounced process callbacks:', error instanceof Error ? error.stack : String(error));
             });
             // Cancel pending IPC requests so plugin tools don't hang
             await cancelAllPendingIpcRequests().catch((e) => {

package/dist/discord-urls.js

@@ -48,6 +48,17 @@ export function discordApiUrl(path) {
 export function createDiscordRest(token) {
     return new REST({ api: getDiscordRestApiUrl() }).setToken(token);
 }
+/**
+ * Returns the internet-reachable base URL for this kimaki instance.
+ * When KIMAKI_INTERNET_REACHABLE_URL is set (e.g. "https://my-kimaki.fly.dev"),
+ * kimaki binds the hrana server to 0.0.0.0 and exposes a /kimaki/wake endpoint
+ * so the gateway-proxy can wake this instance. Discord traffic still flows
+ * through the normal path (gateway-proxy in gateway mode, direct in self-hosted).
+ * Returns null when not set (kimaki only reachable on localhost).
+ */
+export function getInternetReachableBaseUrl() {
+    return process.env['KIMAKI_INTERNET_REACHABLE_URL'] || null;
+}
 /**
  * Derive an HTTPS REST base URL from a WebSocket gateway URL.
  * Swaps wss→https and ws→http. Used for gateway mode where the

package/dist/discord-ws-proxy.js

@@ -0,0 +1,350 @@
+// Discord WS + REST reverse proxy.
+// Mounted on the hrana http.Server to proxy Discord Gateway (WebSocket)
+// and REST API traffic through localhost. This enables cloud deployment
+// where kimaki runs behind a reverse proxy / tunnel.
+//
+// The proxy is always registered on the hrana server for simplicity,
+// but only matters when KIMAKI_INTERNET_REACHABLE_URL is set (which
+// makes discordBaseUrl point to localhost instead of Discord directly).
+//
+// Upstream URL is configurable: in self-hosted mode it's https://discord.com,
+// in gateway mode it's the Rust gateway-proxy (e.g. https://discord-gateway.kimaki.xyz).
+// The upstream is captured at proxy creation time from the current discordBaseUrl.
+//
+// REST proxy: forwards /api/* to upstream /api/*
+// WS proxy:   upgrades /gateway to upstream gateway WS
+//
+// Gateway URL rewrite: intercepts GET /api/v10/gateway/bot responses and
+// rewrites the "url" field to ws://127.0.0.1:{port}/gateway so discord.js
+// connects through the local proxy for WebSocket too.
+//
+// No retry logic — discord.js has its own reconnect/resume. The proxy is
+// transparent: it pipes frames and propagates close events cleanly.
+import http from 'node:http';
+import stream from 'node:stream';
+import WebSocket, { WebSocketServer } from 'ws';
+import { createLogger } from './logger.js';
+const logger = createLogger('PROXY');
+const DEFAULT_REST_BASE = 'https://discord.com';
+const DEFAULT_GATEWAY_BASE = 'wss://gateway.discord.gg';
+/**
+ * Derive an upstream WS gateway URL from a REST base URL.
+ * For discord.com: returns wss://gateway.discord.gg (different host).
+ * For gateway proxies: swaps https→wss / http→ws (same host).
+ */
+export function deriveGatewayBaseFromRest(restBase) {
+    try {
+        const parsed = new URL(restBase);
+        // discord.com uses a different host for the gateway
+        if (parsed.hostname === 'discord.com') {
+            return DEFAULT_GATEWAY_BASE;
+        }
+        // Gateway proxies serve both REST and WS on the same host
+        if (parsed.protocol === 'https:') {
+            parsed.protocol = 'wss:';
+        }
+        else if (parsed.protocol === 'http:') {
+            parsed.protocol = 'ws:';
+        }
+        return parsed.toString().replace(/\/$/, '');
+    }
+    catch {
+        return DEFAULT_GATEWAY_BASE;
+    }
+}
+/**
+ * Create an HTTP request handler that proxies /api/* to an upstream REST API.
+ *
+ * getUpstreamBase resolves the upstream REST base URL at request time.
+ * Called per-request so it picks up the correct upstream even when
+ * credential resolution (gateway vs self-hosted) happens after server start.
+ *
+ * Intercepts GET /api/v10/gateway/bot to rewrite the gateway URL so discord.js
+ * connects through the local WS proxy instead of directly to upstream.
+ */
+export function createDiscordRestProxyHandler({ localPort, getUpstreamBase, getGatewayToken, }) {
+    return async (req, res) => {
+        const url = new URL(req.url || '/', `http://127.0.0.1:${localPort}`);
+        if (!url.pathname.startsWith('/api/')) {
+            // Not a Discord REST path — let other handlers deal with it
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        // Authenticate non-loopback REST requests with the gateway token.
+        // When bound to 0.0.0.0, remote clients must prove they hold the secret
+        // to prevent the proxy being used as an open relay to Discord's API.
+        const remoteAddr = req.socket.remoteAddress || '';
+        const isLoopback = isLoopbackAddress(remoteAddr);
+        if (!isLoopback) {
+            const expectedToken = getGatewayToken();
+            const providedToken = req.headers['x-kimaki-auth'];
+            if (!expectedToken || providedToken !== expectedToken) {
+                res.writeHead(401, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ error: 'unauthorized' }));
+                return;
+            }
+        }
+        const upstreamUrl = new URL(url.pathname + url.search, getUpstreamBase());
+        // Forward headers, replacing Host
+        const headers = {};
+        for (const [key, value] of Object.entries(req.headers)) {
+            if (key === 'host' || key === 'connection') {
+                continue;
+            }
+            if (typeof value === 'string') {
+                headers[key] = value;
+            }
+            else if (Array.isArray(value)) {
+                headers[key] = value.join(', ');
+            }
+        }
+        // Collect request body
+        const chunks = [];
+        for await (const chunk of req) {
+            chunks.push(chunk);
+        }
+        const body = chunks.length > 0 ? Buffer.concat(chunks) : undefined;
+        const upstreamRes = await fetch(upstreamUrl.toString(), {
+            method: req.method || 'GET',
+            headers,
+            body,
+        }).catch((err) => {
+            logger.error(`REST proxy error: ${err.message}`);
+            res.writeHead(502, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: 'upstream_error', message: err.message }));
+            return null;
+        });
+        if (!upstreamRes) {
+            return;
+        }
+        // Intercept /gateway/bot to rewrite the gateway URL
+        const isGatewayBot = url.pathname.endsWith('/gateway/bot');
+        if (isGatewayBot && upstreamRes.ok) {
+            const responseBody = await upstreamRes.json();
+            // Rewrite gateway URL to point to local WS proxy.
+            // Embed the gateway token as a query param so discord.js authenticates
+            // with the WS bridge (discord.js can't set custom headers on WS upgrade).
+            const token = getGatewayToken();
+            const tokenQuery = token ? `?token=${encodeURIComponent(token)}` : '';
+            responseBody.url = `ws://127.0.0.1:${localPort}/gateway${tokenQuery}`;
+            const rewritten = JSON.stringify(responseBody);
+            // Forward relevant response headers
+            const responseHeaders = {
+                'content-type': 'application/json',
+                'content-length': Buffer.byteLength(rewritten).toString(),
+            };
+            copyRateLimitHeaders(upstreamRes.headers, responseHeaders);
+            res.writeHead(upstreamRes.status, responseHeaders);
+            res.end(rewritten);
+            return;
+        }
+        // Forward response as-is
+        const responseHeaders = {};
+        upstreamRes.headers.forEach((value, key) => {
+            // Skip transfer-encoding since we buffer the full response
+            if (key === 'transfer-encoding') {
+                return;
+            }
+            responseHeaders[key] = value;
+        });
+        const responseBody = Buffer.from(await upstreamRes.arrayBuffer());
+        responseHeaders['content-length'] = responseBody.length.toString();
+        res.writeHead(upstreamRes.status, responseHeaders);
+        res.end(responseBody);
+    };
+}
+/**
+ * Check if a socket remote address is loopback.
+ * Accepts IPv6 loopback, IPv4 loopback range, and IPv4-mapped IPv6 loopback.
+ */
+export function isLoopbackAddress(remoteAddr) {
+    return remoteAddr === '::1'
+        || remoteAddr.startsWith('127.')
+        || remoteAddr.startsWith('::ffff:127.');
+}
+/**
+ * Copy Discord rate-limit headers from upstream response to proxy response.
+ */
+function copyRateLimitHeaders(source, target) {
+    const rateLimitHeaders = [
+        'x-ratelimit-limit',
+        'x-ratelimit-remaining',
+        'x-ratelimit-reset',
+        'x-ratelimit-reset-after',
+        'x-ratelimit-bucket',
+        'x-ratelimit-global',
+        'retry-after',
+    ];
+    for (const header of rateLimitHeaders) {
+        const value = source.get(header);
+        if (value) {
+            target[header] = value;
+        }
+    }
+}
+// ── WebSocket bridge/relay ───────────────────────────────────────────────
+//
+// The WS bridge is a rendezvous point for two connections:
+//   1. The gateway-proxy connects inbound (from the internet) on /gateway
+//   2. discord.js connects locally on /gateway
+//
+// The bridge pairs the two and pipes frames bidirectionally.
+// When either side closes, the other side is closed with the same code/reason.
+//
+// Connection ordering: the gateway-proxy may connect before or after discord.js.
+// Unpaired connections wait up to 30s for their counterpart. If no match
+// arrives, the connection is closed with 4000 "no counterpart connected".
+//
+// No retry logic — discord.js has its own reconnect/resume, and the
+// gateway-proxy manages its own reconnection. The bridge is transparent.
+const PAIR_TIMEOUT_MS = 30_000;
+/**
+ * Create a WebSocket upgrade handler that implements the bridge/relay pattern.
+ * The gateway-proxy connects as "upstream" and discord.js connects as "local".
+ * Both connect to /gateway on the hrana server; the bridge pairs them.
+ *
+ * Identification: the gateway-proxy sends a custom header
+ * `X-Kimaki-Role: gateway` on its WS upgrade request. Connections without
+ * this header are treated as local (discord.js) connections.
+ *
+ * Authentication: gateway connections must include an `Authorization` header
+ * with the value `client_id:client_secret` matching the stored gateway token.
+ * Local connections from 127.0.0.1 are always allowed (discord.js).
+ */
+export function createGatewayUpgradeHandler({ getGatewayToken, }) {
+    const wss = new WebSocketServer({ noServer: true });
+    // Waiting connections. At most one of each role waiting at a time.
+    let waitingGateway = null;
+    let waitingLocal = null;
+    function tryPair() {
+        if (!waitingGateway || !waitingLocal) {
+            return;
+        }
+        const gateway = waitingGateway;
+        const local = waitingLocal;
+        waitingGateway = null;
+        waitingLocal = null;
+        clearTimeout(gateway.timer);
+        clearTimeout(local.timer);
+        bridgeConnections(gateway.ws, local.ws);
+    }
+    return (req, socket, head) => {
+        const url = new URL(req.url || '/', 'http://localhost');
+        if (url.pathname !== '/gateway') {
+            socket.destroy();
+            return;
+        }
+        const role = req.headers['x-kimaki-role'] === 'gateway' ? 'gateway' : 'local';
+        // Authenticate ALL connections via Authorization header or query param.
+        // Gateway-proxy sends token as Authorization header.
+        // discord.js sends token as ?token= query param (can't set custom WS headers).
+        // Reject if token is not yet configured (startup race) or doesn't match.
+        const expectedToken = getGatewayToken();
+        const providedToken = req.headers['authorization'] || url.searchParams.get('token');
+        if (!expectedToken || providedToken !== expectedToken) {
+            logger.error(`WS bridge: ${role} connection rejected — ${!expectedToken ? 'token not configured' : 'invalid auth'}`);
+            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            logger.log(`WS bridge: ${role} connection established`);
+            if (role === 'gateway') {
+                // Close any existing waiting gateway connection
+                if (waitingGateway) {
+                    clearTimeout(waitingGateway.timer);
+                    waitingGateway.ws.close(1000, 'replaced by new gateway connection');
+                }
+                const timer = setTimeout(() => {
+                    logger.log('WS bridge: gateway timed out waiting for local');
+                    waitingGateway = null;
+                    ws.close(4000, 'no counterpart connected');
+                }, PAIR_TIMEOUT_MS);
+                waitingGateway = { ws, timer };
+            }
+            else {
+                // Close any existing waiting local connection
+                if (waitingLocal) {
+                    clearTimeout(waitingLocal.timer);
+                    waitingLocal.ws.close(1000, 'replaced by new local connection');
+                }
+                const timer = setTimeout(() => {
+                    logger.log('WS bridge: local timed out waiting for gateway');
+                    waitingLocal = null;
+                    ws.close(4000, 'no counterpart connected');
+                }, PAIR_TIMEOUT_MS);
+                waitingLocal = { ws, timer };
+            }
+            // If a connection closes before being paired, clean up
+            ws.on('close', () => {
+                if (waitingGateway?.ws === ws) {
+                    clearTimeout(waitingGateway.timer);
+                    waitingGateway = null;
+                }
+                if (waitingLocal?.ws === ws) {
+                    clearTimeout(waitingLocal.timer);
+                    waitingLocal = null;
+                }
+            });
+            tryPair();
+        });
+    };
+}
+/**
+ * Bridge two WebSocket connections: pipe frames bidirectionally.
+ * When either side closes, close the other with the same code/reason.
+ */
+function bridgeConnections(gateway, local) {
+    logger.log('WS bridge: paired gateway ↔ local');
+    let gatewayClosed = false;
+    let localClosed = false;
+    // Gateway → Local
+    gateway.on('message', (data, isBinary) => {
+        if (local.readyState === WebSocket.OPEN) {
+            local.send(data, { binary: isBinary });
+        }
+    });
+    // Local → Gateway
+    local.on('message', (data, isBinary) => {
+        if (gateway.readyState === WebSocket.OPEN) {
+            gateway.send(data, { binary: isBinary });
+        }
+    });
+    // Gateway closes → close local
+    gateway.on('close', (code, reason) => {
+        gatewayClosed = true;
+        if (!localClosed) {
+            const closeCode = isValidCloseCode(code) ? code : 1000;
+            local.close(closeCode, reason);
+        }
+    });
+    // Local closes → close gateway
+    local.on('close', (code, reason) => {
+        localClosed = true;
+        if (!gatewayClosed) {
+            const closeCode = isValidCloseCode(code) ? code : 1000;
+            gateway.close(closeCode, reason);
+        }
+    });
+    // Error handling
+    gateway.on('error', (err) => {
+        logger.error(`WS bridge gateway error: ${err.message}`);
+        if (!localClosed) {
+            local.close(1001, 'gateway error');
+        }
+    });
+    local.on('error', (err) => {
+        logger.error(`WS bridge local error: ${err.message}`);
+        if (!gatewayClosed) {
+            gateway.close(1001, 'local error');
+        }
+    });
+}
+/**
+ * WebSocket close codes must be 1000 or in range 3000-4999 for application use.
+ * discord.js uses codes like 4000-4014 for gateway-specific closes.
+ */
+function isValidCloseCode(code) {
+    return code === 1000 || code === 1001 || (code >= 3000 && code <= 4999);
+}