jeopi-cli 16.5.6 → 16.6.1

package/src/messenger/discord.ts

@@ -0,0 +1,382 @@
+import { isRecord, logger } from "jeopi-utils";
+import { MessengerHttpError, messengerFetchJson, splitMessengerText } from "./http";
+import type { MessengerAdapter, MessengerMessage, MessengerPlatformConfig, MessengerTransportDeps } from "./types";
+
+// Protocol: https://docs.discord.com/developers/events/gateway
+// Close codes: https://docs.discord.com/developers/topics/opcodes-and-status-codes
+// REST messages: https://docs.discord.com/developers/resources/message#create-message
+const API = "https://discord.com/api/v10";
+const INTENTS = (1 << 9) | (1 << 12) | (1 << 15);
+const PERMANENT_CLOSE_CODES = new Set([4004, 4010, 4011, 4012, 4013, 4014]);
+
+class DiscordConfigurationError extends Error {}
+
+export interface DiscordClock {
+	/** Schedule once and return an idempotent cancellation function. */
+	schedule(callback: () => void, delayMs: number): () => void;
+	random(): number;
+}
+
+export interface DiscordTransportDeps extends MessengerTransportDeps {
+	clock?: DiscordClock;
+}
+
+const defaultClock: DiscordClock = {
+	schedule(callback, delayMs) {
+		const timer = setTimeout(callback, delayMs);
+		return () => clearTimeout(timer);
+	},
+	random: Math.random,
+};
+
+function waitForReconnect(delayMs: number, signal: AbortSignal, clock: DiscordClock): Promise<void> {
+	if (signal.aborted) return Promise.resolve();
+	const result = Promise.withResolvers<void>();
+	const finish = (): void => {
+		cancel();
+		signal.removeEventListener("abort", finish);
+		result.resolve();
+	};
+	const cancel = clock.schedule(finish, delayMs);
+	signal.addEventListener("abort", finish, { once: true });
+	if (signal.aborted) finish();
+	return result.promise;
+}
+
+interface DiscordSession {
+	id?: string;
+	url?: string;
+	sequence: number | null;
+}
+
+function gatewayUrl(value: unknown): string {
+	let url: URL;
+	try {
+		if (typeof value !== "string") throw new Error();
+		url = new URL(value);
+	} catch {
+		throw new DiscordConfigurationError("Discord returned an invalid Gateway URL");
+	}
+	if (
+		url.protocol !== "wss:" ||
+		!/^gateway(?:-[a-z0-9-]+)?\.discord\.gg$/.test(url.hostname) ||
+		url.username ||
+		url.password ||
+		url.port ||
+		url.hash ||
+		url.pathname !== "/"
+	) {
+		throw new DiscordConfigurationError("Discord returned an untrusted Gateway URL");
+	}
+	url.search = "?v=10&encoding=json";
+	return url.href;
+}
+
+function clearSession(session: DiscordSession): void {
+	session.id = undefined;
+	session.url = undefined;
+	session.sequence = null;
+}
+
+function normalizeMessage(value: unknown, accountId: string): MessengerMessage | undefined {
+	if (!isRecord(value) || !isRecord(value.author)) return;
+	if (value.author.bot || value.webhook_id || value.author.id === accountId) return;
+	if (
+		typeof value.id !== "string" ||
+		!value.id ||
+		typeof value.channel_id !== "string" ||
+		!value.channel_id ||
+		typeof value.author.id !== "string" ||
+		!value.author.id ||
+		typeof value.content !== "string" ||
+		!value.content.trim() ||
+		(value.type !== undefined && value.type !== 0 && value.type !== 19)
+	)
+		return;
+	const mentioned =
+		Array.isArray(value.mentions) && value.mentions.some(user => isRecord(user) && user.id === accountId);
+	const text = value.content.replaceAll(`<@${accountId}>`, "").replaceAll(`<@!${accountId}>`, "").trim();
+	if (!text) return;
+	return {
+		platform: "discord",
+		accountId,
+		channelId: value.channel_id,
+		senderId: value.author.id,
+		messageId: value.id,
+		text,
+		direct: value.guild_id === undefined,
+		mentioned,
+	};
+}
+
+function connectGateway(
+	url: string,
+	token: string,
+	accountId: string,
+	session: DiscordSession,
+	onMessage: (message: MessengerMessage) => Promise<void>,
+	signal: AbortSignal,
+	WebSocketImpl: typeof WebSocket,
+	clock: DiscordClock,
+): Promise<void> {
+	if (signal.aborted) return Promise.resolve();
+	const result = Promise.withResolvers<void>();
+	let socket: WebSocket;
+	try {
+		socket = new WebSocketImpl(url);
+	} catch {
+		clearSession(session);
+		return Promise.resolve();
+	}
+	let finished = false;
+	let hello = false;
+	let established = false;
+	let acknowledged = true;
+	let cancelHeartbeat: (() => void) | undefined;
+	let cancelHandshake: (() => void) | undefined;
+
+	const finish = (error?: Error): void => {
+		if (finished) return;
+		finished = true;
+		// A failed resume handshake must fall back to the initial Gateway.
+		if (!established) clearSession(session);
+		cancelHeartbeat?.();
+		cancelHandshake?.();
+		signal.removeEventListener("abort", abort);
+		socket.removeEventListener("message", receive);
+		socket.removeEventListener("close", close);
+		socket.removeEventListener("error", failed);
+		try {
+			// Normal shutdown invalidates the session; reconnects must preserve it.
+			socket.close(signal.aborted ? 1000 : 4000);
+		} catch {
+			// A failed handshake can already have closed the underlying socket.
+		}
+		if (error) result.reject(error);
+		else result.resolve();
+	};
+	const abort = (): void => finish();
+	const failed = (): void => finish();
+	const send = (op: number, d: unknown): void => {
+		if (finished) return;
+		try {
+			socket.send(JSON.stringify({ op, d }));
+		} catch {
+			finish();
+		}
+	};
+	const heartbeat = (): void => {
+		acknowledged = false;
+		send(1, session.sequence);
+	};
+	const close = (event: CloseEvent): void => {
+		if (PERMANENT_CLOSE_CODES.has(event.code)) {
+			const reason =
+				event.code === 4004
+					? "authentication failed"
+					: event.code === 4013 || event.code === 4014
+						? "message intents are invalid or not enabled"
+						: "Gateway configuration is unsupported";
+			finish(new DiscordConfigurationError(`Discord ${reason} (Gateway ${event.code})`));
+			return;
+		}
+		if ([1000, 1001, 4003, 4007, 4009].includes(event.code)) clearSession(session);
+		finish();
+	};
+	const receive = (event: MessageEvent): void => {
+		if (finished || signal.aborted) return;
+		let packet: unknown;
+		try {
+			if (typeof event.data !== "string") return;
+			packet = JSON.parse(event.data);
+		} catch {
+			finish();
+			return;
+		}
+		if (!isRecord(packet)) return;
+		if (packet.op === 10) {
+			if (hello) return;
+			if (
+				!isRecord(packet.d) ||
+				typeof packet.d.heartbeat_interval !== "number" ||
+				!Number.isFinite(packet.d.heartbeat_interval) ||
+				packet.d.heartbeat_interval <= 0 ||
+				packet.d.heartbeat_interval > 300_000
+			) {
+				finish(new DiscordConfigurationError("Discord returned an invalid heartbeat interval"));
+				return;
+			}
+			hello = true;
+			const interval = packet.d.heartbeat_interval;
+			const tick = (): void => {
+				if (finished) return;
+				if (!acknowledged) {
+					finish();
+					return;
+				}
+				heartbeat();
+				if (!finished) cancelHeartbeat = clock.schedule(tick, interval);
+			};
+			cancelHeartbeat = clock.schedule(tick, clock.random() * interval);
+			if (session.id && session.sequence !== null) {
+				send(6, { token, session_id: session.id, seq: session.sequence });
+			} else {
+				send(2, {
+					token,
+					intents: INTENTS,
+					properties: { os: process.platform, browser: "jeopi", device: "jeopi" },
+				});
+			}
+		} else if (packet.op === 11) {
+			acknowledged = true;
+		} else if (packet.op === 1) {
+			// Unsolicited requests must not shorten the scheduled ACK deadline.
+			send(1, session.sequence);
+		} else if (packet.op === 7 || packet.op === 9) {
+			if (packet.op === 9 && packet.d !== true) clearSession(session);
+			finish();
+		} else if (packet.op === 0) {
+			if (typeof packet.s === "number" && Number.isSafeInteger(packet.s)) session.sequence = packet.s;
+			if (packet.t === "READY") {
+				if (!isRecord(packet.d) || typeof packet.d.session_id !== "string" || !packet.d.session_id) {
+					finish(new DiscordConfigurationError("Discord returned an invalid Gateway session"));
+					return;
+				}
+				try {
+					session.url = gatewayUrl(packet.d.resume_gateway_url);
+				} catch {
+					finish(new DiscordConfigurationError("Discord returned an untrusted resume Gateway URL"));
+					return;
+				}
+				session.id = packet.d.session_id;
+				established = true;
+				cancelHandshake?.();
+			} else if (packet.t === "RESUMED") {
+				established = true;
+				cancelHandshake?.();
+			} else if (packet.t === "MESSAGE_CREATE") {
+				const message = normalizeMessage(packet.d, accountId);
+				if (message) {
+					// The gateway owns authorization, deduplication and its bounded work queue.
+					void Promise.resolve()
+						.then(() => {
+							if (!signal.aborted) return onMessage(message);
+						})
+						.catch(() => logger.warn("Discord message handler failed"));
+				}
+			}
+		}
+	};
+	socket.addEventListener("message", receive);
+	socket.addEventListener("close", close);
+	socket.addEventListener("error", failed);
+	signal.addEventListener("abort", abort, { once: true });
+	cancelHandshake = clock.schedule(() => finish(), 35_000);
+	if (signal.aborted) finish();
+	return result.promise;
+}
+
+export function createDiscordAdapter(
+	config: MessengerPlatformConfig,
+	env: Record<string, string | undefined> = process.env,
+	deps: DiscordTransportDeps = {},
+): MessengerAdapter {
+	const token = env[config.tokenEnv]?.trim();
+	const clock = deps.clock ?? defaultClock;
+	const headers = (): Record<string, string> => {
+		if (!token) throw new DiscordConfigurationError("Discord bot token is missing");
+		return { Authorization: `Bot ${token}`, "Content-Type": "application/json" };
+	};
+	return {
+		platform: "discord",
+		async start(onMessage, signal) {
+			const session: DiscordSession = { sequence: null };
+			let accountId: string | undefined;
+			let initialUrl: string | undefined;
+			let delay = 5_000;
+			while (!signal.aborted) {
+				let retryDelay = delay;
+				try {
+					if (!accountId) {
+						const user = await messengerFetchJson(`${API}/users/@me`, { headers: headers() }, signal, deps.fetch);
+						if (signal.aborted) return;
+						if (!isRecord(user) || typeof user.id !== "string" || !user.id || user.bot !== true) {
+							throw new DiscordConfigurationError("Discord credentials must identify a bot account");
+						}
+						accountId = user.id;
+					}
+					if (!initialUrl) {
+						const gateway = await messengerFetchJson(
+							`${API}/gateway/bot`,
+							{ headers: headers() },
+							signal,
+							deps.fetch,
+						);
+						if (!isRecord(gateway))
+							throw new DiscordConfigurationError("Discord returned invalid Gateway discovery");
+						if (isRecord(gateway.session_start_limit) && gateway.session_start_limit.remaining === 0) {
+							throw new DiscordConfigurationError("Discord Gateway session start limit is exhausted");
+						}
+						initialUrl = gatewayUrl(gateway.url);
+					}
+					await connectGateway(
+						session.url ?? initialUrl,
+						token!,
+						accountId,
+						session,
+						onMessage,
+						signal,
+						deps.WebSocket ?? WebSocket,
+						clock,
+					);
+				} catch (error) {
+					if (signal.aborted) return;
+					if (error instanceof DiscordConfigurationError) throw error;
+					if (
+						error instanceof MessengerHttpError &&
+						error.status >= 400 &&
+						error.status < 500 &&
+						error.status !== 429
+					) {
+						throw new DiscordConfigurationError(
+							`Discord authentication or configuration failed (HTTP ${error.status})`,
+						);
+					}
+					if (error instanceof MessengerHttpError && error.retryAfterMs !== undefined) {
+						retryDelay = Math.max(retryDelay, error.retryAfterMs);
+					}
+					logger.warn("Discord connection failed; retrying");
+				}
+				if (signal.aborted) return;
+				try {
+					await waitForReconnect(retryDelay, signal, clock);
+				} catch {
+					if (signal.aborted) return;
+					throw new Error("Discord reconnect wait failed");
+				}
+				delay = Math.min(delay * 2, 30_000);
+			}
+		},
+		async send(message, text, signal) {
+			const chunks = splitMessengerText(text, 2_000);
+			for (let index = 0; index < chunks.length; index++) {
+				await messengerFetchJson(
+					`${API}/channels/${encodeURIComponent(message.channelId)}/messages`,
+					{
+						method: "POST",
+						headers: headers(),
+						body: JSON.stringify({
+							content: chunks[index],
+							allowed_mentions: { parse: [], replied_user: false },
+							...(index === 0
+								? { message_reference: { message_id: message.messageId, fail_if_not_exists: false } }
+								: {}),
+						}),
+					},
+					signal,
+					deps.fetch,
+				);
+			}
+		},
+	};
+}

package/src/messenger/gateway.ts

@@ -0,0 +1,153 @@
+import { logger } from "jeopi-utils";
+import type { MessengerAdapter, MessengerConfig, MessengerMessage, MessengerReply } from "./types";
+import { MessengerFatalError } from "./types";
+
+const MAX_MESSAGE_LENGTH = 32_000;
+const MAX_QUEUED_MESSAGES = 100;
+const MAX_SEEN_MESSAGES = 10_000;
+
+/** Include the sender even in shared threads: remote histories must not cross users. */
+export function messengerConversationKey(message: MessengerMessage): string {
+	return JSON.stringify([
+		message.platform,
+		message.accountId,
+		message.channelId,
+		message.threadId ?? "",
+		message.senderId,
+	]);
+}
+
+export function isMessengerMessageAllowed(message: MessengerMessage, config: MessengerConfig): boolean {
+	const platform = config.platforms[message.platform];
+	return Boolean(
+		platform &&
+			message.accountId &&
+			message.channelId &&
+			message.senderId &&
+			message.messageId &&
+			message.text.trim() &&
+			message.text.length <= MAX_MESSAGE_LENGTH &&
+			platform.allowedUserIds.includes(message.senderId) &&
+			(!platform.allowedChannelIds || platform.allowedChannelIds.includes(message.channelId)) &&
+			(message.direct || message.mentioned),
+	);
+}
+
+interface PendingMessage {
+	message: MessengerMessage;
+	adapter: MessengerAdapter;
+	signal: AbortSignal;
+	resolve: () => void;
+}
+
+export interface MessengerGateway {
+	run(signal: AbortSignal): Promise<void>;
+	handle(message: MessengerMessage, signal?: AbortSignal): Promise<void>;
+}
+
+export function createMessengerGateway(
+	config: MessengerConfig,
+	adapters: MessengerAdapter[],
+	reply: MessengerReply,
+): MessengerGateway {
+	const byPlatform = new Map(adapters.map(adapter => [adapter.platform, adapter]));
+	if (byPlatform.size !== adapters.length) throw new Error("Duplicate messenger adapter");
+	for (const platform of Object.keys(config.platforms)) {
+		if (!adapters.some(adapter => adapter.platform === platform))
+			throw new Error("Missing configured messenger adapter");
+	}
+	const seen = new Set<string>();
+	const queue: PendingMessage[] = [];
+	const lifetime = new AbortController();
+	let draining: Promise<void> | undefined;
+	let workerActive = false;
+	let running = false;
+	let fatalError: MessengerFatalError | undefined;
+
+	async function drain(): Promise<void> {
+		while (queue.length > 0) {
+			const pending = queue.shift();
+			if (!pending) break;
+			const { message, adapter, signal, resolve } = pending;
+			try {
+				if (signal.aborted) continue;
+				let text: string;
+				try {
+					text = await reply(message, signal);
+				} catch (error) {
+					if (error instanceof MessengerFatalError) {
+						fatalError = error;
+						lifetime.abort();
+						continue;
+					}
+					if (signal.aborted) continue;
+					logger.warn("Messenger agent turn failed", { platform: message.platform });
+					text = "The request could not be completed. Please try again.";
+				}
+				if (!signal.aborted && text.trim()) {
+					// A failed send may already have delivered a chunk: never retry the entire reply.
+					await adapter.send(message, text, signal);
+				}
+			} catch {
+				if (!signal.aborted) logger.warn("Messenger reply delivery failed", { platform: message.platform });
+			} finally {
+				resolve();
+			}
+		}
+		workerActive = false;
+	}
+
+	function handle(message: MessengerMessage, signal?: AbortSignal): Promise<void> {
+		const adapter = byPlatform.get(message.platform);
+		const effectiveSignal = signal ? AbortSignal.any([lifetime.signal, signal]) : lifetime.signal;
+		if (effectiveSignal.aborted || !adapter || !isMessengerMessageAllowed(message, config)) return Promise.resolve();
+		const id = JSON.stringify([message.platform, message.accountId, message.channelId, message.messageId]);
+		if (seen.has(id) || queue.length >= MAX_QUEUED_MESSAGES) return Promise.resolve();
+		seen.add(id);
+		if (seen.size > MAX_SEEN_MESSAGES) {
+			const oldest = seen.values().next().value;
+			if (oldest !== undefined) seen.delete(oldest);
+		}
+		const { promise, resolve } = Promise.withResolvers<void>();
+		queue.push({ message, adapter, signal: effectiveSignal, resolve });
+		if (!workerActive) {
+			workerActive = true;
+			draining = drain();
+		}
+		return promise;
+	}
+
+	return {
+		handle,
+		async run(signal) {
+			if (running || lifetime.signal.aborted) throw new Error("Messenger gateway cannot be restarted");
+			running = true;
+			const abort = (): void => lifetime.abort();
+			signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted) abort();
+			const starts: Promise<void>[] = [];
+			try {
+				if (lifetime.signal.aborted) return;
+				for (const adapter of adapters) {
+					starts.push(
+						Promise.resolve().then(async () => {
+							await adapter.start(message => handle(message), lifetime.signal);
+							if (!lifetime.signal.aborted) throw new Error("Messenger transport stopped unexpectedly");
+						}),
+					);
+				}
+				await Promise.all(starts);
+				if (fatalError) throw fatalError;
+			} catch {
+				if (fatalError) throw fatalError;
+				if (!signal.aborted)
+					throw new Error("Messenger connection failed; check provider credentials, permissions and connectivity");
+			} finally {
+				lifetime.abort();
+				await Promise.allSettled(starts);
+				await draining;
+				signal.removeEventListener("abort", abort);
+			}
+		},
+	};
+}

package/src/messenger/http.ts

@@ -0,0 +1,87 @@
+export class MessengerHttpError extends Error {
+	constructor(
+		readonly status: number,
+		readonly retryAfterMs?: number,
+	) {
+		super(`Messenger request failed (HTTP ${status})`);
+		this.name = "MessengerHttpError";
+	}
+}
+
+/** Provider limits count UTF-16 units; do not bisect supplementary characters. */
+export function splitMessengerText(text: string, limit: number): string[] {
+	if (!Number.isSafeInteger(limit) || limit < 2)
+		throw new Error("Message chunk limit must be an integer of at least two");
+	const chunks: string[] = [];
+	for (let start = 0; start < text.length; ) {
+		let end = Math.min(start + limit, text.length);
+		const last = text.charCodeAt(end - 1);
+		if (end < text.length && last >= 0xd800 && last <= 0xdbff) end--;
+		chunks.push(text.slice(start, end));
+		start = end;
+	}
+	return chunks;
+}
+
+export async function messengerFetchJson(
+	url: string,
+	init: RequestInit,
+	signal?: AbortSignal,
+	fetchImpl: typeof fetch = fetch,
+): Promise<unknown> {
+	const signals = [AbortSignal.timeout(35_000)];
+	if (signal) signals.push(signal);
+	if (init.signal) signals.push(init.signal);
+	const requestSignal = AbortSignal.any(signals);
+	try {
+		const response = await fetchImpl(url, { ...init, redirect: "error", signal: requestSignal });
+		if (!response.ok) {
+			let retryAfterMs: number | undefined;
+			if (response.status === 429) {
+				let seconds = Number(response.headers.get("retry-after"));
+				if (!seconds) {
+					try {
+						const body: unknown = await response.json();
+						if (typeof body === "object" && body !== null) {
+							if ("retry_after" in body && typeof body.retry_after === "number") {
+								seconds = body.retry_after;
+							} else if (
+								"parameters" in body &&
+								typeof body.parameters === "object" &&
+								body.parameters !== null &&
+								"retry_after" in body.parameters &&
+								typeof body.parameters.retry_after === "number"
+							) {
+								seconds = body.parameters.retry_after;
+							}
+						}
+					} catch {
+						/* Retry metadata is optional; never surface provider response text. */
+					}
+				}
+				// Larger delays overflow native timers into immediate retries.
+				if (Number.isFinite(seconds) && seconds > 0) retryAfterMs = Math.min(seconds * 1000, 2_147_483_647);
+			}
+			if (!response.bodyUsed) await response.body?.cancel();
+			throw new MessengerHttpError(response.status, retryAfterMs);
+		}
+		return await response.json();
+	} catch (error) {
+		if (error instanceof MessengerHttpError) throw error;
+		if (signal?.aborted || init.signal?.aborted) throw new Error("Messenger request cancelled");
+		throw new Error("Messenger request failed");
+	}
+}
+
+export async function waitForMessengerRetry(ms: number, signal: AbortSignal): Promise<void> {
+	if (signal.aborted) return;
+	const { promise, resolve } = Promise.withResolvers<void>();
+	const done = (): void => {
+		clearTimeout(timer);
+		signal.removeEventListener("abort", done);
+		resolve();
+	};
+	const timer = setTimeout(done, ms);
+	signal.addEventListener("abort", done, { once: true });
+	await promise;
+}