jeopi-cli 16.5.6 → 16.6.2

package/src/messenger/config.ts

@@ -0,0 +1,111 @@
+import * as path from "node:path";
+import type { MessengerConfig, MessengerPlatform, MessengerPlatformConfig } from "./types";
+
+const PLATFORMS: MessengerPlatform[] = ["discord", "telegram", "slack"];
+const TOOLS: Record<string, true> = { read: true, grep: true, glob: true, bash: true, edit: true, write: true };
+
+function object(value: unknown, label: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new Error(`${label} must be an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function keys(value: Record<string, unknown>, allowed: string[], label: string): void {
+	if (Object.keys(value).some(key => !allowed.includes(key))) throw new Error(`${label} contains an unknown setting`);
+}
+
+function string(value: unknown, label: string): string {
+	if (typeof value !== "string" || value.trim() !== value || !value || /[\u0000-\u001f\u007f]/u.test(value)) {
+		throw new Error(`${label} must be a nonempty string without surrounding whitespace or control characters`);
+	}
+	return value;
+}
+
+function ids(value: unknown, label: string): string[] {
+	if (!Array.isArray(value) || value.length === 0) throw new Error(`${label} must be a nonempty list of exact IDs`);
+	const result = value.map(item => string(item, label));
+	if (result.some(id => /[\s*]/u.test(id)) || new Set(result).size !== result.length) {
+		throw new Error(`${label} must contain unique exact IDs, without whitespace or wildcards`);
+	}
+	return result;
+}
+
+function envName(value: unknown, fallback: string, label: string): string {
+	const result = value === undefined ? fallback : string(value, label);
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(result)) throw new Error(`${label} must name an environment variable`);
+	return result;
+}
+
+export function parseMessengerConfig(value: unknown, baseDir: string): MessengerConfig {
+	const input = object(value, "Messenger config");
+	keys(input, ["cwd", "sessionDir", "toolNames", "platforms"], "Messenger config");
+	const platformsInput = object(input.platforms, "platforms");
+	keys(platformsInput, PLATFORMS, "platforms");
+	if (Object.keys(platformsInput).length === 0) throw new Error("At least one messenger platform is required");
+	const platforms: MessengerConfig["platforms"] = {};
+	for (const platform of PLATFORMS) {
+		if (!Object.hasOwn(platformsInput, platform)) continue;
+		const item = object(platformsInput[platform], `${platform} config`);
+		keys(
+			item,
+			platform === "slack"
+				? ["tokenEnv", "appTokenEnv", "allowedUserIds", "allowedChannelIds"]
+				: ["tokenEnv", "allowedUserIds", "allowedChannelIds"],
+			`${platform} config`,
+		);
+		const config: MessengerPlatformConfig = {
+			tokenEnv: envName(item.tokenEnv, `JEOPI_${platform.toUpperCase()}_BOT_TOKEN`, `${platform}.tokenEnv`),
+			allowedUserIds: ids(item.allowedUserIds, `${platform}.allowedUserIds`),
+		};
+		if (platform === "slack")
+			config.appTokenEnv = envName(item.appTokenEnv, "JEOPI_SLACK_APP_TOKEN", "slack.appTokenEnv");
+		if (item.allowedChannelIds !== undefined)
+			config.allowedChannelIds = ids(item.allowedChannelIds, `${platform}.allowedChannelIds`);
+		platforms[platform] = config;
+	}
+	const toolNames = input.toolNames === undefined ? [] : input.toolNames;
+	if (
+		!Array.isArray(toolNames) ||
+		toolNames.some(name => typeof name !== "string" || !Object.hasOwn(TOOLS, name)) ||
+		new Set(toolNames).size !== toolNames.length
+	) {
+		throw new Error("toolNames must be a unique list drawn from read, grep, glob, bash, edit, write");
+	}
+	return {
+		cwd: path.resolve(baseDir, input.cwd === undefined ? "." : string(input.cwd, "cwd")),
+		sessionDir: path.resolve(
+			baseDir,
+			input.sessionDir === undefined ? ".jeopi/messenger-sessions" : string(input.sessionDir, "sessionDir"),
+		),
+		toolNames: [...toolNames] as string[],
+		platforms,
+	};
+}
+
+export async function loadMessengerConfig(file: string): Promise<MessengerConfig> {
+	let value: unknown;
+	try {
+		value = await Bun.file(file).json();
+	} catch {
+		throw new Error("Cannot read messenger configuration as JSON");
+	}
+	return parseMessengerConfig(value, path.dirname(path.resolve(file)));
+}
+
+export function validateMessengerEnvironment(
+	config: MessengerConfig,
+	env: Record<string, string | undefined> = process.env,
+): void {
+	for (const platform of PLATFORMS) {
+		const item = config.platforms[platform];
+		if (!item) continue;
+		for (const name of [item.tokenEnv, item.appTokenEnv]) {
+			if (name === undefined) continue;
+			const token = env[name];
+			if (!token?.trim() || token !== token.trim() || /[\s\u0000-\u001f\u007f]/u.test(token)) {
+				throw new Error(`${platform} requires a nonempty credential in ${name}`);
+			}
+		}
+	}
+}

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);
+			}
+		},
+	};
+}