hyperclaw 5.3.45 → 5.4.1

package/dist/agents-routing-eLjVYBAk.js

@@ -0,0 +1,424 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+const require_paths = require('./paths-AIyBxIzm.js');
+const require_paths$1 = require('./paths-DPovhojT.js');
+const chalk = require_chunk.__toESM(require("chalk"));
+const inquirer = require_chunk.__toESM(require("inquirer"));
+const fs_extra = require_chunk.__toESM(require("fs-extra"));
+const path = require_chunk.__toESM(require("path"));
+
+//#region src/routing/session-key.ts
+/**
+
+* Compute the canonical session key for an inbound message context.
+
+*/
+function computeSessionKey(ctx) {
+	const { agentId, channel, peerKind, peerId, threadId, topicId, dmScope } = ctx;
+	if (peerKind === "dm") {
+		if (dmScope === "main" || dmScope === void 0) return `agent:${agentId}:main`;
+		return `agent:${agentId}:${channel}:dm:${peerId}`;
+	}
+	if (peerKind === "group") {
+		let key$1 = `agent:${agentId}:${channel}:group:${peerId}`;
+		if (topicId) key$1 += `:topic:${topicId}`;
+		if (threadId) key$1 += `:thread:${threadId}`;
+		return key$1;
+	}
+	let key = `agent:${agentId}:${channel}:channel:${peerId}`;
+	if (threadId) key += `:thread:${threadId}`;
+	return key;
+}
+
+//#endregion
+//#region src/routing/agents-routing.ts
+require_paths$1.init_paths();
+function defaultAgent() {
+	const hcDir = require_paths.getHyperClawDir();
+	return {
+		id: "main",
+		name: "main",
+		workspace: path.default.join(hcDir, "workspace"),
+		default: true
+	};
+}
+var AgentRouter = class {
+	config;
+	constructor(config) {
+		this.config = config ?? this._loadConfig();
+	}
+	_loadConfig() {
+		const cfgPath = require_paths.getConfigPath();
+		const hcDir = require_paths.getHyperClawDir();
+		const routingFile = path.default.join(hcDir, "routing.json");
+		const legacyBindingsFile = path.default.join(hcDir, "agent-bindings.json");
+		let fromMain = false;
+		try {
+			const mainCfg = fs_extra.default.readJsonSync(cfgPath);
+			const bindings = mainCfg?.bindings;
+			const agentsList = mainCfg?.agents?.list;
+			if (Array.isArray(bindings) || Array.isArray(agentsList)) {
+				fromMain = true;
+				return {
+					agents: { list: agentsList && agentsList.length > 0 ? agentsList : [defaultAgent()] },
+					bindings: Array.isArray(bindings) ? bindings : [],
+					session: mainCfg?.session || { dmScope: "main" },
+					broadcast: mainCfg?.broadcast,
+					channels: mainCfg?.channels
+				};
+			}
+		} catch {}
+		try {
+			const legacy = fs_extra.default.readJsonSync(routingFile);
+			if (legacy?.bindings?.length || legacy?.agents?.list?.length) return this._migrateToMain(legacy, cfgPath);
+		} catch {}
+		try {
+			const arr = fs_extra.default.readJsonSync(legacyBindingsFile);
+			if (Array.isArray(arr) && arr.length > 0) {
+				const bindings = arr.map((b) => ({
+					match: { channel: b.channelId },
+					agentId: b.agentName,
+					createdAt: (/* @__PURE__ */ new Date()).toISOString()
+				}));
+				const migrated = {
+					agents: { list: [defaultAgent()] },
+					bindings,
+					session: { dmScope: "main" }
+				};
+				return this._migrateToMain(migrated, cfgPath);
+			}
+		} catch {}
+		return {
+			agents: { list: [defaultAgent()] },
+			bindings: [],
+			session: { dmScope: "main" }
+		};
+	}
+	_migrateToMain(legacy, cfgPath) {
+		try {
+			let current = {};
+			if (fs_extra.default.existsSync(cfgPath)) current = fs_extra.default.readJsonSync(cfgPath);
+			const next = {
+				...current,
+				bindings: legacy.bindings ?? [],
+				agents: {
+					...current?.agents,
+					list: legacy.agents?.list ?? [defaultAgent()]
+				},
+				...legacy.broadcast ? { broadcast: legacy.broadcast } : {},
+				...legacy.session ? { session: legacy.session } : {}
+			};
+			fs_extra.default.ensureDirSync(path.default.dirname(cfgPath));
+			fs_extra.default.writeJsonSync(cfgPath, next, { spaces: 2 });
+		} catch (e) {
+			console.warn("[agents-routing] Migration write failed:", e.message);
+		}
+		return legacy;
+	}
+	async _saveConfig() {
+		const { ConfigStore } = await Promise.resolve().then(() => require("./config-qJUYRMzx.js"));
+		const store = new ConfigStore();
+		const current = await store.load();
+		await store.patch({
+			bindings: this.config.bindings ?? [],
+			agents: {
+				...current?.agents,
+				list: this.config.agents?.list ?? [defaultAgent()]
+			},
+			...this.config.broadcast ? { broadcast: this.config.broadcast } : {},
+			...this.config.session ? { session: this.config.session } : {}
+		});
+	}
+	route(msg) {
+		const agents = this.config.agents?.list ?? [defaultAgent()];
+		const bindings = this.config.bindings ?? [];
+		const broadcastAgents = this._resolveBroadcast(msg);
+		const matched = this._matchBinding(msg, bindings, agents);
+		const agentDef = matched.agentDef;
+		const sessionKey = this._computeKey(msg, agentDef.id);
+		const skipLastRoute = msg.isDM ? this._shouldSkipLastRoute(msg) : false;
+		return {
+			agentId: agentDef.id,
+			agentDef,
+			sessionKey,
+			matchedBy: matched.matchedBy,
+			...broadcastAgents.length > 1 ? { broadcast: broadcastAgents } : {},
+			...skipLastRoute ? { skipLastRoute: true } : {}
+		};
+	}
+	_matchBinding(msg, bindings, agents) {
+		const find = (id) => agents.find((a) => a.id === id) ?? defaultAgent();
+		for (const b of bindings) {
+			if (!this._matchesFilter(msg, b.match)) continue;
+			return {
+				agentDef: find(b.agentId),
+				matchedBy: this._describeMatch(b.match)
+			};
+		}
+		const def = agents.find((a) => a.default) ?? agents[0] ?? defaultAgent();
+		return {
+			agentDef: def,
+			matchedBy: "default"
+		};
+	}
+	_matchesFilter(msg, match) {
+		if (match.channel && match.channel !== msg.channel) return false;
+		if (match.accountId && match.accountId !== "*" && match.accountId !== msg.accountId) return false;
+		if (match.peer) {
+			if (match.peer.kind !== msg.peer.kind) return false;
+			if (match.peer.id !== msg.peer.id) return false;
+		}
+		if (match.guildId && match.guildId !== msg.guildId) return false;
+		if (match.roles?.length) {
+			const senderRoles = msg.roles ?? [];
+			if (!match.roles.every((r) => senderRoles.includes(r))) return false;
+		}
+		if (match.teamId && match.teamId !== msg.teamId) return false;
+		return true;
+	}
+	_describeMatch(m) {
+		const parts = [];
+		if (m.channel) parts.push(`channel=${m.channel}`);
+		if (m.peer) parts.push(`peer=${m.peer.kind}:${m.peer.id}`);
+		if (m.guildId) parts.push(`guild=${m.guildId}`);
+		if (m.teamId) parts.push(`team=${m.teamId}`);
+		if (m.accountId) parts.push(`account=${m.accountId}`);
+		return parts.join(" ") || "channel-match";
+	}
+	_computeKey(msg, agentId) {
+		const dmScope = this.config.session?.dmScope ?? "main";
+		const ctx = {
+			agentId,
+			channel: msg.channel,
+			peerKind: msg.isDM ? "dm" : msg.peer.kind,
+			peerId: msg.peer.id,
+			threadId: msg.threadId,
+			topicId: msg.topicId,
+			dmScope: msg.isDM ? dmScope : void 0
+		};
+		return computeSessionKey(ctx);
+	}
+	_resolveBroadcast(msg) {
+		const bc = this.config.broadcast;
+		if (!bc) return [];
+		const agentIds = bc[msg.peer.id] ?? bc[msg.senderId];
+		if (Array.isArray(agentIds)) return agentIds;
+		return [];
+	}
+	/**
+	* Returns true when the inbound DM sender is not the pinned owner.
+	* Pinned owner = the single non-wildcard allowFrom entry for this channel.
+	*/
+	_shouldSkipLastRoute(msg) {
+		const chanCfg = this.config.channels?.[msg.channel];
+		if (!chanCfg?.allowFrom) return false;
+		const nonWild = chanCfg.allowFrom.filter((id) => id !== "*" && id !== "**");
+		if (nonWild.length !== 1) return false;
+		const pinnedOwner = nonWild[0];
+		return msg.senderId !== pinnedOwner;
+	}
+	resolveDefaultAccount(channelId) {
+		return this.config.channels?.[channelId]?.defaultAccount;
+	}
+	listBindings() {
+		const agents = this.config.agents?.list ?? [];
+		const bindings = this.config.bindings ?? [];
+		console.log(chalk.default.bold.cyan("\n  🦅 AGENT BINDINGS\n"));
+		if (agents.length === 0) {
+			console.log(chalk.default.gray("  No agents configured.\n"));
+			return;
+		}
+		for (const a of agents) {
+			const def = a.default ? chalk.default.green(" [default]") : "";
+			const model = a.model ? chalk.default.gray(` model:${a.model}`) : "";
+			console.log(`  ${chalk.default.bold(a.id)}${def}  ${chalk.default.gray(a.workspace)}${model}`);
+		}
+		console.log();
+		if (bindings.length === 0) {
+			console.log(chalk.default.gray("  No explicit bindings — all traffic → default agent.\n"));
+			return;
+		}
+		console.log(chalk.default.bold("  Bindings:\n"));
+		for (const b of bindings) {
+			const m = b.match;
+			const parts = [];
+			if (m.channel) parts.push(chalk.default.cyan(m.channel));
+			if (m.peer) parts.push(`peer:${m.peer.kind}/${chalk.default.white(m.peer.id)}`);
+			if (m.guildId) parts.push(`guild:${chalk.default.white(m.guildId)}`);
+			if (m.teamId) parts.push(`team:${chalk.default.white(m.teamId)}`);
+			if (m.roles?.length) parts.push(`roles:[${m.roles.join(",")}]`);
+			if (m.accountId) parts.push(`account:${m.accountId}`);
+			console.log(`  ${parts.join("  ")} ${chalk.default.gray("→")} ${chalk.default.bold(b.agentId)}`);
+		}
+		const bc = this.config.broadcast;
+		if (bc) {
+			console.log(chalk.default.bold("\n  Broadcast groups:\n"));
+			const strat = bc.strategy ?? "parallel";
+			for (const [peerId, agents$1] of Object.entries(bc)) {
+				if (peerId === "strategy") continue;
+				if (Array.isArray(agents$1)) console.log(`  ${chalk.default.white(peerId)}  ${chalk.default.gray(`→ [${agents$1.join(", ")}]`)}  ${chalk.default.gray(`(${strat})`)}`);
+			}
+		}
+		console.log();
+	}
+	async bind() {
+		console.log(chalk.default.cyan("\n  Bind a channel/peer to an agent\n"));
+		const { channel, matchType } = await inquirer.default.prompt([{
+			type: "input",
+			name: "channel",
+			message: "Channel ID (e.g. telegram, discord, slack, whatsapp):",
+			validate: (v) => v.trim().length > 0 || "Required"
+		}, {
+			type: "list",
+			name: "matchType",
+			message: "Match by:",
+			choices: [
+				{
+					name: "Any message on this channel",
+					value: "channel"
+				},
+				{
+					name: "Specific peer (group ID, user ID, channel ID)",
+					value: "peer"
+				},
+				{
+					name: "Discord guild",
+					value: "guild"
+				},
+				{
+					name: "Slack team",
+					value: "team"
+				},
+				{
+					name: "Account ID",
+					value: "account"
+				}
+			]
+		}]);
+		const match = { channel };
+		if (matchType === "peer") {
+			const { kind, peerId } = await inquirer.default.prompt([{
+				type: "list",
+				name: "kind",
+				message: "Peer type:",
+				choices: [
+					"group",
+					"channel",
+					"dm",
+					"room"
+				]
+			}, {
+				type: "input",
+				name: "peerId",
+				message: "Peer ID:",
+				validate: (v) => v.trim().length > 0 || "Required"
+			}]);
+			match.peer = {
+				kind,
+				id: peerId
+			};
+		} else if (matchType === "guild") {
+			const { guildId } = await inquirer.default.prompt([{
+				type: "input",
+				name: "guildId",
+				message: "Discord guild ID:",
+				validate: (v) => v.trim().length > 0 || "Required"
+			}]);
+			match.guildId = guildId;
+		} else if (matchType === "team") {
+			const { teamId } = await inquirer.default.prompt([{
+				type: "input",
+				name: "teamId",
+				message: "Slack team ID:",
+				validate: (v) => v.trim().length > 0 || "Required"
+			}]);
+			match.teamId = teamId;
+		} else if (matchType === "account") {
+			const { accountId } = await inquirer.default.prompt([{
+				type: "input",
+				name: "accountId",
+				message: "Account ID:",
+				validate: (v) => v.trim().length > 0 || "Required"
+			}]);
+			match.accountId = accountId;
+		}
+		const agentIds = (this.config.agents?.list ?? []).map((a) => a.id);
+		const { agentId } = await inquirer.default.prompt([{
+			type: agentIds.length > 1 ? "list" : "input",
+			name: "agentId",
+			message: "Route to agent ID:",
+			choices: agentIds.length > 1 ? agentIds : void 0,
+			default: agentIds[0] ?? "main"
+		}]);
+		if (!this.config.bindings) this.config.bindings = [];
+		this.config.bindings.unshift({
+			match,
+			agentId,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		await this._saveConfig();
+		console.log(chalk.default.green(`\n  ✔  Binding added: ${channel}/${matchType} → ${agentId}\n`));
+	}
+	async unbind() {
+		const bindings = this.config.bindings ?? [];
+		if (bindings.length === 0) {
+			console.log(chalk.default.gray("\n  No bindings to remove.\n"));
+			return;
+		}
+		const { toRemove } = await inquirer.default.prompt([{
+			type: "checkbox",
+			name: "toRemove",
+			message: "Select bindings to remove:",
+			choices: bindings.map((b, i) => ({
+				name: `${this._describeMatch(b.match)} → ${b.agentId}`,
+				value: i
+			}))
+		}]);
+		for (const idx of toRemove.sort((a, b) => b - a)) bindings.splice(idx, 1);
+		this.config.bindings = bindings;
+		await this._saveConfig();
+		console.log(chalk.default.green(`\n  ✔  Removed ${toRemove.length} binding(s)\n`));
+	}
+	getConfig() {
+		return this.config;
+	}
+	getAgents() {
+		return this.config.agents?.list ?? [defaultAgent()];
+	}
+	getBindings() {
+		return this.config.bindings ?? [];
+	}
+};
+/** Infer agent from workspace (TUI agent inference). Best match = longest workspace prefix. */
+function inferAgentFromWorkspace(cwd, cfg) {
+	const list = cfg?.agents?.list;
+	if (!Array.isArray(list) || list.length === 0) return null;
+	const resolvedCwd = path.default.resolve(cwd);
+	let best = null;
+	let bestLen = 0;
+	for (const a of list) {
+		const ws = a.workspace;
+		if (!ws || typeof ws !== "string") continue;
+		const resolvedWs = path.default.resolve(ws);
+		if (resolvedCwd === resolvedWs || resolvedCwd.startsWith(resolvedWs + path.default.sep)) {
+			if (resolvedWs.length > bestLen) {
+				bestLen = resolvedWs.length;
+				best = a;
+			}
+		}
+	}
+	return best;
+}
+
+//#endregion
+Object.defineProperty(exports, 'AgentRouter', {
+  enumerable: true,
+  get: function () {
+    return AgentRouter;
+  }
+});
+Object.defineProperty(exports, 'inferAgentFromWorkspace', {
+  enumerable: true,
+  get: function () {
+    return inferAgentFromWorkspace;
+  }
+});

package/dist/api-key-validation-BANgbsfO.js

@@ -0,0 +1,66 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+
+//#region src/infra/api-key-validation.ts
+/**
+
+* src/infra/api-key-validation.ts
+
+* M-5: API key format/prefix validation for known providers.
+
+* Returns an error message if invalid, null if valid or unknown provider.
+
+*/
+/** Prefix patterns for known providers (loose format check) */
+const PROVIDER_PREFIXES = {
+	anthropic: "sk-ant-",
+	"anthropic-setup-token": "sk-ant-setup-",
+	openai: "sk-",
+	openrouter: "sk-or-",
+	google: "AIza",
+	xai: "xai-",
+	tavily: "tvly-",
+	"opencode-zen": "oc-",
+	"opencode-go": "oc-",
+	"vercel-ai": "vercel_",
+	groq: "gsk_",
+	perplexity: "pplx-"
+};
+/** Minimum length per provider (provider may allow shorter, this is a sanity check) */
+const MIN_LENGTH = {
+	anthropic: 20,
+	"anthropic-setup-token": 20,
+	openai: 20,
+	openrouter: 20,
+	google: 20,
+	xai: 20,
+	tavily: 20,
+	"opencode-zen": 10,
+	"opencode-go": 10,
+	"vercel-ai": 20,
+	groq: 20
+};
+/**
+
+* Validate API key format for a known provider.
+
+* @param providerId - Provider ID (e.g. anthropic, openrouter)
+
+* @param key - The API key to validate
+
+* @returns Error message if invalid, null if valid
+
+*/
+function validateApiKeyFormat(providerId, key) {
+	const k = (key || "").trim();
+	if (k.length < 8) return "API key is too short";
+	const pid = providerId.toLowerCase().replace(/[^a-z0-9-]/g, "");
+	const prefix = PROVIDER_PREFIXES[pid];
+	if (!prefix) return null;
+	if (!k.startsWith(prefix)) return `Expected key to start with "${prefix}" for ${providerId}. Double-check you copied the full key.`;
+	const min = MIN_LENGTH[pid];
+	if (min && k.length < min) return `API key seems too short for ${providerId}`;
+	return null;
+}
+
+//#endregion
+exports.validateApiKeyFormat = validateApiKeyFormat;

package/dist/api-key-validation-Bnz-0MMK.js

@@ -0,0 +1,66 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+
+//#region src/infra/api-key-validation.ts
+/**
+
+* src/infra/api-key-validation.ts
+
+* M-5: API key format/prefix validation for known providers.
+
+* Returns an error message if invalid, null if valid or unknown provider.
+
+*/
+/** Prefix patterns for known providers (loose format check) */
+const PROVIDER_PREFIXES = {
+	anthropic: "sk-ant-",
+	"anthropic-setup-token": "sk-ant-setup-",
+	openai: "sk-",
+	openrouter: "sk-or-",
+	google: "AIza",
+	xai: "xai-",
+	tavily: "tvly-",
+	"opencode-zen": "oc-",
+	"opencode-go": "oc-",
+	"vercel-ai": "vercel_",
+	groq: "gsk_",
+	perplexity: "pplx-"
+};
+/** Minimum length per provider (provider may allow shorter, this is a sanity check) */
+const MIN_LENGTH = {
+	anthropic: 20,
+	"anthropic-setup-token": 20,
+	openai: 20,
+	openrouter: 20,
+	google: 20,
+	xai: 20,
+	tavily: 20,
+	"opencode-zen": 10,
+	"opencode-go": 10,
+	"vercel-ai": 20,
+	groq: 20
+};
+/**
+
+* Validate API key format for a known provider.
+
+* @param providerId - Provider ID (e.g. anthropic, openrouter)
+
+* @param key - The API key to validate
+
+* @returns Error message if invalid, null if valid
+
+*/
+function validateApiKeyFormat(providerId, key) {
+	const k = (key || "").trim();
+	if (k.length < 8) return "API key is too short";
+	const pid = providerId.toLowerCase().replace(/[^a-z0-9-]/g, "");
+	const prefix = PROVIDER_PREFIXES[pid];
+	if (!prefix) return null;
+	if (!k.startsWith(prefix)) return `Expected key to start with "${prefix}" for ${providerId}. Double-check you copied the full key.`;
+	const min = MIN_LENGTH[pid];
+	if (min && k.length < min) return `API key seems too short for ${providerId}`;
+	return null;
+}
+
+//#endregion
+exports.validateApiKeyFormat = validateApiKeyFormat;

package/dist/api-key-validation-D_fMCaO5.js

@@ -0,0 +1,66 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+
+//#region src/infra/api-key-validation.ts
+/**
+
+* src/infra/api-key-validation.ts
+
+* M-5: API key format/prefix validation for known providers.
+
+* Returns an error message if invalid, null if valid or unknown provider.
+
+*/
+/** Prefix patterns for known providers (loose format check) */
+const PROVIDER_PREFIXES = {
+	anthropic: "sk-ant-",
+	"anthropic-setup-token": "sk-ant-setup-",
+	openai: "sk-",
+	openrouter: "sk-or-",
+	google: "AIza",
+	xai: "xai-",
+	tavily: "tvly-",
+	"opencode-zen": "oc-",
+	"opencode-go": "oc-",
+	"vercel-ai": "vercel_",
+	groq: "gsk_",
+	perplexity: "pplx-"
+};
+/** Minimum length per provider (provider may allow shorter, this is a sanity check) */
+const MIN_LENGTH = {
+	anthropic: 20,
+	"anthropic-setup-token": 20,
+	openai: 20,
+	openrouter: 20,
+	google: 20,
+	xai: 20,
+	tavily: 20,
+	"opencode-zen": 10,
+	"opencode-go": 10,
+	"vercel-ai": 20,
+	groq: 20
+};
+/**
+
+* Validate API key format for a known provider.
+
+* @param providerId - Provider ID (e.g. anthropic, openrouter)
+
+* @param key - The API key to validate
+
+* @returns Error message if invalid, null if valid
+
+*/
+function validateApiKeyFormat(providerId, key) {
+	const k = (key || "").trim();
+	if (k.length < 8) return "API key is too short";
+	const pid = providerId.toLowerCase().replace(/[^a-z0-9-]/g, "");
+	const prefix = PROVIDER_PREFIXES[pid];
+	if (!prefix) return null;
+	if (!k.startsWith(prefix)) return `Expected key to start with "${prefix}" for ${providerId}. Double-check you copied the full key.`;
+	const min = MIN_LENGTH[pid];
+	if (min && k.length < min) return `API key seems too short for ${providerId}`;
+	return null;
+}
+
+//#endregion
+exports.validateApiKeyFormat = validateApiKeyFormat;

package/dist/api-key-validation-Db7rG3JU.js

@@ -0,0 +1,66 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+
+//#region src/infra/api-key-validation.ts
+/**
+
+* src/infra/api-key-validation.ts
+
+* M-5: API key format/prefix validation for known providers.
+
+* Returns an error message if invalid, null if valid or unknown provider.
+
+*/
+/** Prefix patterns for known providers (loose format check) */
+const PROVIDER_PREFIXES = {
+	anthropic: "sk-ant-",
+	"anthropic-setup-token": "sk-ant-setup-",
+	openai: "sk-",
+	openrouter: "sk-or-",
+	google: "AIza",
+	xai: "xai-",
+	tavily: "tvly-",
+	"opencode-zen": "oc-",
+	"opencode-go": "oc-",
+	"vercel-ai": "vercel_",
+	groq: "gsk_",
+	perplexity: "pplx-"
+};
+/** Minimum length per provider (provider may allow shorter, this is a sanity check) */
+const MIN_LENGTH = {
+	anthropic: 20,
+	"anthropic-setup-token": 20,
+	openai: 20,
+	openrouter: 20,
+	google: 20,
+	xai: 20,
+	tavily: 20,
+	"opencode-zen": 10,
+	"opencode-go": 10,
+	"vercel-ai": 20,
+	groq: 20
+};
+/**
+
+* Validate API key format for a known provider.
+
+* @param providerId - Provider ID (e.g. anthropic, openrouter)
+
+* @param key - The API key to validate
+
+* @returns Error message if invalid, null if valid
+
+*/
+function validateApiKeyFormat(providerId, key) {
+	const k = (key || "").trim();
+	if (k.length < 8) return "API key is too short";
+	const pid = providerId.toLowerCase().replace(/[^a-z0-9-]/g, "");
+	const prefix = PROVIDER_PREFIXES[pid];
+	if (!prefix) return null;
+	if (!k.startsWith(prefix)) return `Expected key to start with "${prefix}" for ${providerId}. Double-check you copied the full key.`;
+	const min = MIN_LENGTH[pid];
+	if (min && k.length < min) return `API key seems too short for ${providerId}`;
+	return null;
+}
+
+//#endregion
+exports.validateApiKeyFormat = validateApiKeyFormat;