jeo-code 0.12.6 → 0.12.8

package/src/commands/messenger.ts

@@ -0,0 +1,146 @@
+import * as fs from "node:fs/promises";
+import { constants } from "node:fs";
+import * as path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+import { loadMessengerConfig, validateMessengerEnvironment } from "../messenger/config";
+import { createDiscordAdapter } from "../messenger/discord";
+import { setupDiscordMessenger } from "../messenger/discord-setup";
+import { messengerArtifactPrompt } from "../messenger/artifacts";
+import { createMessengerGateway, messengerSessionRoute } from "../messenger/gateway";
+import { createMessengerSessionPool } from "../messenger/session-pool";
+import { createSlackAdapter } from "../messenger/slack";
+import { createTelegramAdapter } from "../messenger/telegram";
+import type { MessengerAdapter, MessengerConfig, MessengerReply } from "../messenger/types";
+import { createSession } from "../agent/session";
+
+type Flags = { config?: string; channel: string[]; user: string[]; tools?: string; artifacts: boolean; service: boolean; noDm: boolean };
+
+function parse(args: string[]): { action: "setup" | "check" | "run"; flags: Flags } {
+	const action = args.shift();
+	if (action !== "setup" && action !== "check" && action !== "run") throw new Error("Usage: jeo messenger setup|check|run --config <file>");
+	const flags: Flags = { channel: [], user: [], artifacts: false, service: false, noDm: false };
+	for (let index = 0; index < args.length; index++) {
+		const arg = args[index]!;
+		if (arg === "--artifacts") flags.artifacts = true;
+		else if (arg === "--service") flags.service = true;
+		else if (arg === "--no-dm") flags.noDm = true;
+		else if (["--config", "--channel", "--user", "--tools"].includes(arg)) {
+			const value = args[++index];
+			if (!value || value.startsWith("--")) throw new Error(`${arg} requires a value`);
+			if (arg === "--config") flags.config = value;
+			else if (arg === "--tools") flags.tools = value;
+			else flags[arg === "--channel" ? "channel" : "user"].push(...value.split(",").filter(Boolean));
+		} else throw new Error(`Unknown messenger option: ${arg}`);
+	}
+	if (!flags.config) throw new Error("Messenger requires --config <file>");
+	return { action, flags };
+}
+
+function terminalIO() {
+	let muted = false;
+	const output = new Writable({ write(chunk, _encoding, callback) { if (!muted) process.stdout.write(chunk); callback(); } });
+	const rl = createInterface({ input: process.stdin, output, terminal: Boolean(process.stdin.isTTY && process.stdout.isTTY) });
+	const ask = async (question: string, secret = false) => {
+		process.stdout.write(question);
+		muted = secret;
+		try { return (await rl.question("")).trim(); }
+		finally { muted = false; if (secret) process.stdout.write("\n"); }
+	};
+	return {
+		interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+		say: (line: string) => process.stdout.write(`${line}\n`),
+		ask: (question: string) => ask(question),
+		askSecret: (question: string) => ask(question, true),
+		close: () => rl.close(),
+	};
+}
+
+function routeUuid(config: MessengerConfig, message: Parameters<MessengerReply>[0]): string {
+	const hex = messengerSessionRoute(config.cwd, message);
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+
+/** Run each conversation in its own reusable agent process. */
+export function createMessengerCliReply(config: MessengerConfig, spawn: typeof Bun.spawn = Bun.spawn): MessengerReply & { close(): Promise<void> } {
+	const pool = createMessengerSessionPool(spawn);
+	const reply: MessengerReply = async (message, signal, onActivity) => {
+		if (signal.aborted) throw new Error("Messenger request aborted");
+		const id = routeUuid(config, message);
+		await fs.mkdir(config.sessionDir, { recursive: true, mode: 0o700 });
+		const target = path.join(config.sessionDir, `${id}.jsonl`);
+		const legacy = path.join(config.cwd, ".jeo", "sessions", `${id}.jsonl`);
+		try {
+			await fs.access(target);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+			let old;
+			try { old = await fs.open(legacy, constants.O_RDONLY | constants.O_NOFOLLOW); }
+			catch (openError) { if ((openError as NodeJS.ErrnoException).code !== "ENOENT") throw openError; }
+			try {
+				if (old) {
+					if (!(await old.stat()).isFile()) throw new Error("Invalid legacy messenger session");
+					const contents = await old.readFile();
+					const temporary = `${target}.${crypto.randomUUID()}.tmp`;
+					try {
+						await fs.writeFile(temporary, contents, { flag: "wx", mode: 0o600 });
+						await fs.link(temporary, target);
+					} finally { await fs.unlink(temporary).catch(() => {}); }
+				} else {
+					await createSession(config.cwd, id, undefined, config.sessionDir, true);
+				}
+			} catch (createError) {
+				if ((createError as NodeJS.ErrnoException).code !== "EEXIST") throw createError;
+			} finally { await old?.close(); }
+		}
+		const artifactPrompt = await messengerArtifactPrompt(config.platforms[message.platform]?.artifactDir, message, signal);
+		const executable = process.execPath;
+		const sourceEntry = process.argv[1]?.endsWith(".ts") ? process.argv[1] : undefined;
+		const tools = [...new Set(config.toolNames.map(name => name === "grep" ? "search" : name === "glob" ? "find" : name))];
+		const toolFlags = tools.length ? ["--tools", tools.join(",")] : ["--no-tools"];
+		const command = [executable, ...(sourceEntry ? ["--no-env-file", sourceEntry] : []), "launch", "--print", "--no-tui", "--no-skills", "--literal-worker", ...toolFlags, "--resume", id, "--", "worker"];
+		const secretNames = new Set<string>();
+		for (const platform of Object.values(config.platforms)) {
+			if (!platform) continue;
+			secretNames.add(platform.tokenEnv);
+			if (platform.appTokenEnv) secretNames.add(platform.appTokenEnv);
+			for (const name of [platform.tokenEnv, platform.appTokenEnv]) {
+				if (name?.startsWith("JEO_")) secretNames.add(`JEOPI_${name.slice(4)}`);
+				if (name?.startsWith("JEOPI_")) secretNames.add(`JEO_${name.slice(6)}`);
+			}
+		}
+		const env = Object.fromEntries(Object.entries(process.env).filter(([name, value]) => value !== undefined && !secretNames.has(name))) as Record<string, string>;
+		for (const name of secretNames) env[name] = "";
+		env.JEO_SESSION_DIR = config.sessionDir;
+		return pool.turn(id, command, config.cwd, env, [message.text, artifactPrompt].filter(Boolean).join("\n\n"), signal, onActivity);
+	};
+	return Object.assign(reply, { close: pool.close });
+}
+
+export async function runMessengerCommand(args: string[]): Promise<void> {
+	const { action, flags } = parse([...args]);
+	if (action === "setup") {
+		const io = terminalIO();
+		try {
+			const result = await setupDiscordMessenger({ configPath: path.resolve(flags.config!), channelIds: flags.channel.length ? flags.channel : undefined, userIds: flags.user.length ? flags.user : undefined, toolNames: flags.tools?.split(",").filter(Boolean), artifacts: flags.artifacts, service: flags.service, dmTest: !flags.noDm }, io);
+			process.stdout.write(`Discord messenger ready: ${result.configPath}\nStart: ${result.runScript}\n`);
+		} finally { io.close(); }
+		return;
+	}
+	let config: MessengerConfig;
+	try { config = await loadMessengerConfig(flags.config!); validateMessengerEnvironment(config); }
+	catch { throw new Error("Messenger configuration or required environment is invalid"); }
+	const platforms = Object.keys(config.platforms);
+	if (action === "check") { process.stdout.write(`Messenger configuration valid: ${platforms.join(", ")}; ${config.toolNames.length} tools enabled. No network checks performed.\n`); return; }
+	if (config.toolNames.length) process.stderr.write("Warning: messenger tools grant authorized remote users local machine authority; this is not a sandbox.\n");
+	const adapters: MessengerAdapter[] = [];
+	if (config.platforms.discord) adapters.push(createDiscordAdapter(config.platforms.discord));
+	if (config.platforms.telegram) adapters.push(createTelegramAdapter(config.platforms.telegram));
+	if (config.platforms.slack) adapters.push(createSlackAdapter(config.platforms.slack));
+	const controller = new AbortController();
+	const stop = () => controller.abort();
+	process.once("SIGINT", stop); process.once("SIGTERM", stop);
+	const reply = createMessengerCliReply(config);
+	try { process.stdout.write(`Starting messenger: ${platforms.join(", ")}. Press Ctrl+C to stop.\n`); await createMessengerGateway(config, adapters, reply, { concurrency: 4 }).run(controller.signal); }
+	finally { controller.abort(); await reply.close(); process.off("SIGINT", stop); process.off("SIGTERM", stop); }
+}

package/src/commands/notify.ts

@@ -107,6 +107,7 @@ async function runSetup(flags: Flags, opts: NotifyOptions): Promise<void> {
     console.log(`Slack bot and channel verified; channelId=${channelId}. Notifications enabled. Setup did not send a message.`);
     console.log("Socket Mode URL verified; app-token ownership and socket connectivity are checked by the daemon handshake. Token rotation requires an explicit user allowlist.");
   } else if (flags.provider === "discord") {
+    console.log("Discord setup: enable Message Content Intent in the Developer Portal, invite the bot with View Channel, Send Messages, Read Message History, and Send Messages in Threads, then copy IDs with Discord Developer Mode.");
     const channelId = flags.channelId ?? existing?.discord?.channelId ?? await question("Discord channel ID: ", opts);
     const sameDestination = existing?.discord?.botToken === token && existing.discord.channelId === channelId;
     if (!allowedUserIds?.length && (!sameDestination || !existing?.discord?.allowedUserIds?.length)) allowedUserIds = (await question("Allowed Discord user IDs (comma separated; required after token/destination changes): ", opts)).split(",").map(id => id.trim());
@@ -121,6 +122,7 @@ async function runSetup(flags: Flags, opts: NotifyOptions): Promise<void> {
       const unchanged = previous?.botToken === token && previous.channelId === channelId;
       const owners = allowedUserIds ?? (unchanged ? previous.allowedUserIds : undefined);
       if (!owners?.length || !owners.every(id => /^[1-9]\d{0,19}$/.test(id))) throw new Error("Discord requires explicit allowed user IDs; repeat --allowed-user-ids after token or destination changes");
+      if ([10, 11, 12].includes(channel.type) && (!channel.owner_id || !owners.includes(channel.owner_id))) throw new Error("Discord thread owner must be an allowed user");
       return { notifications: { ...raw.notifications, enabled: true, discord: { ...(unchanged ? previous : {}), botToken: token, channelId, allowedUserIds: owners } } };
     });
     console.log(`Discord bot verified; channelId=${channelId}. Notifications enabled.`);
@@ -209,6 +211,7 @@ async function runHealth(provider: Provider, send: boolean, opts: NotifyOptions)
     const me = await api.getMe();
     const channel = await api.getChannel(cfg.channelId);
     if (!me.bot || channel.id !== cfg.channelId || ![0, 1, 5, 10, 11, 12].includes(channel.type)) throw new Error("Discord identity/channel validation failed");
+    if ([10, 11, 12].includes(channel.type) && (!channel.owner_id || !cfg.allowedUserIds.includes(channel.owner_id))) throw new Error("Discord thread owner must be an allowed user");
     if (send) await api.sendMessage(cfg.channelId, "jeo notification test");
   } else {
     const cfg = n?.telegram;

package/src/messenger/activity.ts

@@ -0,0 +1,30 @@
+import type { AgentLoopEvents, ToolInvocation } from "../agent/engine";
+import type { MessengerActivityReporter } from "./types";
+
+/**
+ * Derive one-line progress from session events: the model's declared tool intent (falling back to the
+ * tool name) and long-running lifecycle notices. Raw tool arguments, results and errors never surface.
+ */
+export function createMessengerActivityEvents(report: MessengerActivityReporter): AgentLoopEvents {
+	let step = 0;
+	return {
+		onAssistant(_raw: string, invocation: ToolInvocation | null) {
+			if (!invocation || invocation.tool === "done") return;
+			step++;
+			const intent =
+				invocation.arguments &&
+				typeof invocation.arguments.i === "string" &&
+				invocation.arguments.i.trim()
+					? invocation.arguments.i.trim()
+					: `Using ${invocation.tool}`;
+			report(`Step ${step} · ${intent}`);
+		},
+		onNotice(message: string) {
+			if (/compact/i.test(message)) {
+				report("Compacting context");
+			} else if (/retry|rate limit/i.test(message)) {
+				report("Retrying after a provider error");
+			}
+		},
+	};
+}

package/src/messenger/artifacts.ts

@@ -0,0 +1,167 @@
+import * as fsConstants from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { messengerConversationKey } from "./gateway";
+import type { MessengerMessage } from "./types";
+
+const MAX_ARTIFACT_SIZE = 8 * 1024 * 1024;
+const CDN_HOSTS: Record<string, true> = { "cdn.discordapp.com": true, "media.discordapp.net": true };
+const MAX_ARTIFACTS = 10;
+
+export function messengerArtifactDirectory(root: string, message: MessengerMessage): string {
+	const route = new Bun.CryptoHasher("sha256").update(messengerConversationKey(message)).digest("hex");
+	return path.join(root, route);
+}
+
+export async function prepareMessengerArtifactDirectory(root: string, message: MessengerMessage): Promise<string> {
+	const rootStat = await fs.lstat(root);
+	if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error("Invalid artifact directory");
+	const directory = messengerArtifactDirectory(root, message);
+	await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+	const stat = await fs.lstat(directory);
+	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Invalid artifact directory");
+	return directory;
+}
+
+async function withAbort<T>(operation: () => Promise<T>, signal: AbortSignal): Promise<T> {
+	if (signal.aborted) throw new Error("Attachment download aborted");
+	const stopped = Promise.withResolvers<never>();
+	const abort = (): void => stopped.reject(new Error("Attachment download aborted"));
+	signal.addEventListener("abort", abort, { once: true });
+	try {
+		return await Promise.race([operation(), stopped.promise]);
+	} finally {
+		signal.removeEventListener("abort", abort);
+	}
+}
+
+export async function downloadMessengerAttachments(
+	directory: string,
+	message: MessengerMessage,
+	signal: AbortSignal,
+	fetchImpl: typeof fetch = fetch,
+	timeoutMs = 30_000,
+): Promise<string[]> {
+	const attachments = message.attachments ?? [];
+	if (attachments.length > MAX_ARTIFACTS) throw new Error("Too many attachments");
+	const paths: string[] = [];
+	for (const [index, attachment] of attachments.entries()) {
+		const url = new URL(attachment.url);
+		if (
+			!Object.hasOwn(CDN_HOSTS, url.hostname) ||
+			url.protocol !== "https:" ||
+			url.port ||
+			url.username ||
+			url.password ||
+			!url.pathname.startsWith("/attachments/")
+		)
+			throw new Error("Invalid attachment URL");
+		if (!Number.isSafeInteger(attachment.size) || attachment.size < 0 || attachment.size > MAX_ARTIFACT_SIZE)
+			throw new Error("Invalid attachment size");
+		const downloadSignal = AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
+		const response = await withAbort(
+			() => fetchImpl(url, { signal: downloadSignal, redirect: "error" }),
+			downloadSignal,
+		);
+		if (!response.ok || !response.body) throw new Error("Attachment download failed");
+		const reader = response.body.getReader();
+		const chunks: Uint8Array[] = [];
+		let size = 0;
+		try {
+			while (true) {
+				const { done, value } = await withAbort(() => reader.read(), downloadSignal);
+				if (done) break;
+				size += value.byteLength;
+				if (size > MAX_ARTIFACT_SIZE || size > attachment.size) throw new Error("Attachment exceeds declared size");
+				chunks.push(value);
+			}
+		} finally {
+			void reader.cancel().catch(() => {});
+		}
+		if (size !== attachment.size) throw new Error("Attachment size mismatch");
+		const safeName =
+			path
+				.basename(attachment.filename)
+				.replace(/[^a-zA-Z0-9._-]/gu, "_")
+				.slice(0, 100) || "attachment";
+		const id = new Bun.CryptoHasher("sha256").update(message.messageId).digest("hex");
+		const file = path.join(directory, `input-${id}-${index}-${safeName}`);
+		await fs.writeFile(file, Buffer.concat(chunks), { flag: "wx", mode: 0o600 });
+		paths.push(file);
+	}
+	return paths;
+}
+
+export async function messengerArtifactPrompt(
+	root: string | undefined,
+	message: MessengerMessage,
+	signal: AbortSignal,
+): Promise<string> {
+	if (!root) {
+		if (message.attachments?.length) throw new Error("Discord attachments are not enabled");
+		return "";
+	}
+	const directory = await prepareMessengerArtifactDirectory(root, message);
+	const inputs = await downloadMessengerAttachments(directory, message, signal);
+	const base = `To deliver a requested file, write it inside ${directory} and put [artifact:relative/path] on its own line in your final response. Only files in that directory can be uploaded; each must be at most 8 MiB. Never include credentials or secrets in output files.`;
+	return inputs.length ? `${base}\nIncoming files: ${inputs.join(", ")}` : base;
+}
+
+export async function readMessengerArtifacts(
+	root: string,
+	message: MessengerMessage,
+	text: string,
+): Promise<{
+	text: string;
+	files: { name: string; data: Uint8Array }[];
+}> {
+	const names: string[] = [];
+	const cleaned = text
+		.replace(/^\s*\[artifact:([^\]\r\n]+)\]\s*$/gmu, (_match, name: string) => {
+			names.push(name);
+			return "";
+		})
+		.trim();
+	if (names.length > MAX_ARTIFACTS) throw new Error("Too many output files");
+	if (!names.length) return { text, files: [] };
+	const directory = await prepareMessengerArtifactDirectory(root, message);
+	const files: { name: string; data: Uint8Array }[] = [];
+	for (const name of names) {
+		if (
+			!name ||
+			path.isAbsolute(name) ||
+			name.includes("\\") ||
+			name.split("/").some(part => !part || part === "." || part === "..")
+		) {
+			throw new Error("Invalid output file path");
+		}
+		let current = path.resolve(directory);
+		for (const part of name.split("/")) {
+			current = path.join(current, part);
+			const entry = await fs.lstat(current);
+			if (entry.isSymbolicLink()) throw new Error("Output file symlinks are not allowed");
+		}
+		if (!(await fs.lstat(current)).isFile()) throw new Error("Output file is not a regular file");
+		const handle = await fs.open(
+			current,
+			fsConstants.constants.O_RDONLY | fsConstants.constants.O_NOFOLLOW | fsConstants.constants.O_NONBLOCK,
+		);
+		try {
+			const stat = await handle.stat();
+			if (!stat.isFile() || stat.size > MAX_ARTIFACT_SIZE)
+				throw new Error("Output file is invalid or exceeds 8 MiB");
+			const data = Buffer.alloc(stat.size + 1);
+			let offset = 0;
+			while (offset < data.length) {
+				const { bytesRead } = await handle.read(data, offset, data.length - offset, offset);
+				if (!bytesRead) break;
+				offset += bytesRead;
+			}
+			if (offset !== stat.size) throw new Error("Output file changed while being read");
+			files.push({ name: path.basename(name), data: data.subarray(0, offset) });
+		} finally {
+			await handle.close();
+		}
+	}
+	return { text: cleaned, files };
+}

package/src/messenger/config.ts

@@ -0,0 +1,145 @@
+import * as fs from "node:fs/promises";
+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,
+	find: true,
+	search: 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;
+}
+
+/** Resolve a platform credential from `env`, honoring JEO_<X> <-> JEOPI_<X> aliases when using default names. */
+export function resolveMessengerToken(
+	name: string | undefined,
+	env: Record<string, string | undefined> = process.env,
+): string | undefined {
+	if (!name) return undefined;
+	const direct = env[name];
+	if (direct !== undefined) return direct;
+	if (name.startsWith("JEO_")) return env[`JEOPI_${name.slice(4)}`];
+	if (name.startsWith("JEOPI_")) return env[`JEO_${name.slice(6)}`];
+	return undefined;
+}
+
+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"]
+				: platform === "discord"
+					? ["tokenEnv", "allowedUserIds", "allowedChannelIds", "artifactDir"]
+					: ["tokenEnv", "allowedUserIds", "allowedChannelIds"],
+			`${platform} config`,
+		);
+		const config: MessengerPlatformConfig = {
+			tokenEnv: envName(item.tokenEnv, `JEO_${platform.toUpperCase()}_BOT_TOKEN`, `${platform}.tokenEnv`),
+			allowedUserIds: ids(item.allowedUserIds, `${platform}.allowedUserIds`),
+		};
+		if (platform === "slack")
+			config.appTokenEnv = envName(item.appTokenEnv, "JEO_SLACK_APP_TOKEN", "slack.appTokenEnv");
+		if (item.allowedChannelIds !== undefined)
+			config.allowedChannelIds = ids(item.allowedChannelIds, `${platform}.allowedChannelIds`);
+		if (platform === "discord" && item.artifactDir !== undefined)
+			config.artifactDir = path.resolve(baseDir, string(item.artifactDir, "discord.artifactDir"));
+		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 ? ".jeo/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");
+	}
+	const config = parseMessengerConfig(value, path.dirname(path.resolve(file)));
+	const artifactDir = config.platforms.discord?.artifactDir;
+	if (artifactDir) {
+		const stat = await fs.lstat(artifactDir).catch(() => undefined);
+		if (!stat?.isDirectory() || stat.isSymbolicLink())
+			throw new Error("discord.artifactDir must be an existing directory, not a symlink");
+	}
+	return config;
+}
+
+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 = resolveMessengerToken(name, env);
+			if (!token?.trim() || token !== token.trim() || /[\s\u0000-\u001f\u007f]/u.test(token)) {
+				throw new Error(`${platform} requires a nonempty credential in ${name}`);
+			}
+		}
+	}
+}