@kodelyth/twitch 2026.5.39 → 2026.5.42

package/dist/plugin-BMzrFFQR.js

@@ -0,0 +1,1285 @@
+import { a as getAccountConfig, c as resolveTwitchAccountContext, d as isAccountConfigured, f as missingTargetError, h as resolveTwitchToken, i as DEFAULT_ACCOUNT_ID, l as resolveTwitchSnapshotAccountId, m as normalizeTwitchChannel, o as listAccountIds, p as normalizeToken, r as twitchSetupWizard, s as resolveDefaultTwitchAccountId, t as twitchSetupAdapter, u as generateMessageId } from "./setup-surface-CovnRl9R.js";
+import { describeAccountSnapshot } from "klaw/plugin-sdk/account-helpers";
+import { buildChannelConfigSchema } from "klaw/plugin-sdk/channel-config-schema";
+import { createChatChannelPlugin } from "klaw/plugin-sdk/channel-core";
+import { createLoggedPairingApprovalNotifier, createPairingPrefixStripper } from "klaw/plugin-sdk/channel-pairing";
+import { buildPassiveProbedChannelStatusSummary, runStoppablePassiveMonitor } from "klaw/plugin-sdk/extension-shared";
+import { createComputedAccountStatusAdapter, createDefaultChannelRuntimeState } from "klaw/plugin-sdk/status-helpers";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
+import { createMessageReceiptFromOutboundResults, defineChannelMessageAdapter } from "klaw/plugin-sdk/channel-message";
+import { RefreshingAuthProvider, StaticAuthProvider } from "@twurple/auth";
+import { ChatClient, LogLevel } from "@twurple/chat";
+import { MarkdownConfigSchema } from "klaw/plugin-sdk/channel-config-primitives";
+import { z } from "zod";
+import { ApiClient } from "@twurple/api";
+//#region extensions/twitch/src/twitch-client.ts
+/**
+* Manages Twitch chat client connections
+*/
+var TwitchClientManager = class {
+	constructor(logger) {
+		this.logger = logger;
+		this.clients = /* @__PURE__ */ new Map();
+		this.messageHandlers = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Create an auth provider for the account.
+	*/
+	async createAuthProvider(account, normalizedToken) {
+		if (!account.clientId) throw new Error("Missing Twitch client ID");
+		if (account.clientSecret) {
+			const authProvider = new RefreshingAuthProvider({
+				clientId: account.clientId,
+				clientSecret: account.clientSecret
+			});
+			await authProvider.addUserForToken({
+				accessToken: normalizedToken,
+				refreshToken: account.refreshToken ?? null,
+				expiresIn: account.expiresIn ?? null,
+				obtainmentTimestamp: account.obtainmentTimestamp ?? Date.now()
+			}).then((userId) => {
+				this.logger.info(`Added user ${userId} to RefreshingAuthProvider for ${account.username}`);
+			}).catch((err) => {
+				this.logger.error(`Failed to add user to RefreshingAuthProvider: ${formatErrorMessage(err)}`);
+			});
+			authProvider.onRefresh((userId, token) => {
+				this.logger.info(`Access token refreshed for user ${userId} (expires in ${token.expiresIn ? `${token.expiresIn}s` : "unknown"})`);
+			});
+			authProvider.onRefreshFailure((userId, error) => {
+				this.logger.error(`Failed to refresh access token for user ${userId}: ${error.message}`);
+			});
+			const refreshStatus = account.refreshToken ? "automatic token refresh enabled" : "token refresh disabled (no refresh token)";
+			this.logger.info(`Using RefreshingAuthProvider for ${account.username} (${refreshStatus})`);
+			return authProvider;
+		}
+		this.logger.info(`Using StaticAuthProvider for ${account.username} (no clientSecret provided)`);
+		return new StaticAuthProvider(account.clientId, normalizedToken);
+	}
+	/**
+	* Get or create a chat client for an account
+	*/
+	async getClient(account, cfg, accountId) {
+		const key = this.getAccountKey(account);
+		const existing = this.clients.get(key);
+		if (existing) return existing;
+		const tokenResolution = resolveTwitchToken(cfg, { accountId });
+		if (!tokenResolution.token) {
+			this.logger.error(`Missing Twitch token for account ${account.username} (set channels.twitch.accounts.${account.username}.token or KLAW_TWITCH_ACCESS_TOKEN for default)`);
+			throw new Error("Missing Twitch token");
+		}
+		this.logger.debug?.(`Using ${tokenResolution.source} token source for ${account.username}`);
+		if (!account.clientId) {
+			this.logger.error(`Missing Twitch client ID for account ${account.username}`);
+			throw new Error("Missing Twitch client ID");
+		}
+		const normalizedToken = normalizeToken(tokenResolution.token);
+		const client = new ChatClient({
+			authProvider: await this.createAuthProvider(account, normalizedToken),
+			channels: [account.channel],
+			rejoinChannelsOnReconnect: true,
+			requestMembershipEvents: true,
+			logger: {
+				minLevel: LogLevel.WARNING,
+				custom: { log: (level, message) => {
+					switch (level) {
+						case LogLevel.CRITICAL:
+							this.logger.error(message);
+							break;
+						case LogLevel.ERROR:
+							this.logger.error(message);
+							break;
+						case LogLevel.WARNING:
+							this.logger.warn(message);
+							break;
+						case LogLevel.INFO:
+							this.logger.info(message);
+							break;
+						case LogLevel.DEBUG:
+							this.logger.debug?.(message);
+							break;
+						case LogLevel.TRACE:
+							this.logger.debug?.(message);
+							break;
+					}
+				} }
+			}
+		});
+		this.setupClientHandlers(client, account);
+		client.connect();
+		this.clients.set(key, client);
+		this.logger.info(`Connected to Twitch as ${account.username}`);
+		return client;
+	}
+	/**
+	* Set up message and event handlers for a client
+	*/
+	setupClientHandlers(client, account) {
+		const key = this.getAccountKey(account);
+		client.onMessage((channelName, _user, messageText, msg) => {
+			const handler = this.messageHandlers.get(key);
+			if (handler) {
+				const normalizedChannel = channelName.startsWith("#") ? channelName.slice(1) : channelName;
+				const from = `twitch:${msg.userInfo.userName}`;
+				const preview = messageText.slice(0, 100).replace(/\n/g, "\\n");
+				this.logger.debug?.(`twitch inbound: channel=${normalizedChannel} from=${from} len=${messageText.length} preview="${preview}"`);
+				handler({
+					username: msg.userInfo.userName,
+					displayName: msg.userInfo.displayName,
+					userId: msg.userInfo.userId,
+					message: messageText,
+					channel: normalizedChannel,
+					id: msg.id,
+					timestamp: /* @__PURE__ */ new Date(),
+					isMod: msg.userInfo.isMod,
+					isOwner: msg.userInfo.isBroadcaster,
+					isVip: msg.userInfo.isVip,
+					isSub: msg.userInfo.isSubscriber,
+					chatType: "group"
+				});
+			}
+		});
+		this.logger.info(`Set up handlers for ${key}`);
+	}
+	/**
+	* Set a message handler for an account
+	* @returns A function that removes the handler when called
+	*/
+	onMessage(account, handler) {
+		const key = this.getAccountKey(account);
+		this.messageHandlers.set(key, handler);
+		return () => {
+			this.messageHandlers.delete(key);
+		};
+	}
+	/**
+	* Disconnect a client
+	*/
+	async disconnect(account) {
+		const key = this.getAccountKey(account);
+		const client = this.clients.get(key);
+		if (client) {
+			client.quit();
+			this.clients.delete(key);
+			this.messageHandlers.delete(key);
+			this.logger.info(`Disconnected ${key}`);
+		}
+	}
+	/**
+	* Disconnect all clients
+	*/
+	async disconnectAll() {
+		this.clients.forEach((client) => client.quit());
+		this.clients.clear();
+		this.messageHandlers.clear();
+		this.logger.info(" Disconnected all clients");
+	}
+	/**
+	* Send a message to a channel
+	*/
+	async sendMessage(account, channel, message, cfg, accountId) {
+		try {
+			const client = await this.getClient(account, cfg, accountId);
+			const messageId = crypto.randomUUID();
+			await client.say(channel, message);
+			return {
+				ok: true,
+				messageId
+			};
+		} catch (error) {
+			this.logger.error(`Failed to send message: ${formatErrorMessage(error)}`);
+			return {
+				ok: false,
+				error: formatErrorMessage(error)
+			};
+		}
+	}
+	/**
+	* Generate a unique key for an account
+	*/
+	getAccountKey(account) {
+		return `${account.username}:${account.channel}`;
+	}
+	/**
+	* Clear all clients and handlers (for testing)
+	*/
+	clearForTest() {
+		this.clients.clear();
+		this.messageHandlers.clear();
+	}
+};
+//#endregion
+//#region extensions/twitch/src/client-manager-registry.ts
+/**
+* Client manager registry for Twitch plugin.
+*
+* Manages the lifecycle of TwitchClientManager instances across the plugin,
+* ensuring proper cleanup when accounts are stopped or reconfigured.
+*/
+/**
+* Global registry of client managers.
+* Keyed by account ID.
+*/
+const registry = /* @__PURE__ */ new Map();
+/**
+* Get or create a client manager for an account.
+*
+* @param accountId - The account ID
+* @param logger - Logger instance
+* @returns The client manager
+*/
+function getOrCreateClientManager(accountId, logger) {
+	const existing = registry.get(accountId);
+	if (existing) return existing.manager;
+	const manager = new TwitchClientManager(logger);
+	registry.set(accountId, {
+		manager,
+		accountId,
+		logger,
+		createdAt: Date.now()
+	});
+	logger.info(`Registered client manager for account: ${accountId}`);
+	return manager;
+}
+/**
+* Get an existing client manager for an account.
+*
+* @param accountId - The account ID
+* @returns The client manager, or undefined if not registered
+*/
+function getClientManager(accountId) {
+	return registry.get(accountId)?.manager;
+}
+/**
+* Disconnect and remove a client manager from the registry.
+*
+* @param accountId - The account ID
+* @returns Promise that resolves when cleanup is complete
+*/
+async function removeClientManager(accountId) {
+	const entry = registry.get(accountId);
+	if (!entry) return;
+	await entry.manager.disconnectAll();
+	registry.delete(accountId);
+	entry.logger.info(`Unregistered client manager for account: ${accountId}`);
+}
+//#endregion
+//#region extensions/twitch/src/utils/markdown.ts
+/**
+* Markdown utilities for Twitch chat
+*
+* Twitch chat doesn't support markdown formatting, so we strip it before sending.
+* Based on Klaw's markdownToText in src/agents/tools/web-fetch-utils.ts.
+*/
+/**
+* Strip markdown formatting from text for Twitch compatibility.
+*
+* Removes images, links, bold, italic, strikethrough, code blocks, inline code,
+* headers, and list formatting. Replaces newlines with spaces since Twitch
+* is a single-line chat medium.
+*
+* @param markdown - The markdown text to strip
+* @returns Plain text with markdown removed
+*/
+function stripMarkdownForTwitch(markdown) {
+	return markdown.replace(/!\[[^\]]*]\([^)]+\)/g, "").replace(/\[([^\]]+)]\([^)]+\)/g, "$1").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/__([^_]+)__/g, "$1").replace(/\*([^*]+)\*/g, "$1").replace(/_([^_]+)_/g, "$1").replace(/~~([^~]+)~~/g, "$1").replace(/```[\s\S]*?```/g, (block) => block.replace(/```[^\n]*\n?/g, "").replace(/```/g, "")).replace(/`([^`]+)`/g, "$1").replace(/^#{1,6}\s+/gm, "").replace(/^\s*[-*+]\s+/gm, "").replace(/^\s*\d+\.\s+/gm, "").replace(/\r/g, "").replace(/[ \t]+\n/g, "\n").replace(/\n/g, " ").replace(/[ \t]{2,}/g, " ").trim();
+}
+/**
+* Simple word-boundary chunker for Twitch (500 char limit).
+* Strips markdown before chunking to avoid breaking markdown patterns.
+*
+* @param text - The text to chunk
+* @param limit - Maximum characters per chunk (Twitch limit is 500)
+* @returns Array of text chunks
+*/
+function chunkTextForTwitch(text, limit) {
+	const cleaned = stripMarkdownForTwitch(text);
+	if (!cleaned) return [];
+	if (limit <= 0) return [cleaned];
+	if (cleaned.length <= limit) return [cleaned];
+	const chunks = [];
+	let remaining = cleaned;
+	while (remaining.length > limit) {
+		const window = remaining.slice(0, limit);
+		const lastSpaceIndex = window.lastIndexOf(" ");
+		if (lastSpaceIndex === -1) {
+			chunks.push(window);
+			remaining = remaining.slice(limit);
+		} else {
+			chunks.push(window.slice(0, lastSpaceIndex));
+			remaining = remaining.slice(lastSpaceIndex + 1);
+		}
+	}
+	if (remaining) chunks.push(remaining);
+	return chunks;
+}
+//#endregion
+//#region extensions/twitch/src/send.ts
+/**
+* Twitch message sending functions with dependency injection support.
+*
+* These functions are the primary interface for sending messages to Twitch.
+* They support dependency injection via the `deps` parameter for testability.
+*/
+function createTwitchSendReceipt(params) {
+	const messageId = params.messageId.trim();
+	const conversationId = params.channel?.trim();
+	return createMessageReceiptFromOutboundResults({
+		results: params.visible === true && messageId && messageId !== "skipped" ? [{
+			channel: "twitch",
+			messageId,
+			...conversationId ? { conversationId } : {}
+		}] : [],
+		kind: "text"
+	});
+}
+/**
+* Internal send function used by the outbound adapter.
+*
+* This function has access to the full Klaw config and handles
+* account resolution, markdown stripping, and actual message sending.
+*
+* @param channel - The channel name
+* @param text - The message text
+* @param cfg - Full Klaw configuration
+* @param accountId - Account ID to use
+* @param stripMarkdown - Whether to strip markdown (default: true)
+* @param logger - Logger instance
+* @returns Result with message ID and status
+*
+* @example
+* const result = await sendMessageTwitchInternal(
+*   "#mychannel",
+*   "Hello Twitch!",
+*   klawConfig,
+*   "default",
+*   true,
+*   console,
+* );
+*/
+async function sendMessageTwitchInternal(channel, text, cfg, accountId, stripMarkdown = true, logger = console) {
+	const { account, configured, availableAccountIds, accountId: resolvedAccountId } = resolveTwitchAccountContext(cfg, accountId);
+	if (!account) return {
+		ok: false,
+		messageId: generateMessageId(),
+		receipt: createTwitchSendReceipt({
+			messageId: "",
+			channel,
+			visible: false
+		}),
+		error: `Account not found: ${accountId ?? "(default)"}. Available accounts: ${availableAccountIds.join(", ") || "none"}`
+	};
+	if (!configured) return {
+		ok: false,
+		messageId: generateMessageId(),
+		receipt: createTwitchSendReceipt({
+			messageId: "",
+			channel,
+			visible: false
+		}),
+		error: `Account ${resolvedAccountId} is not properly configured. Required: username, clientId, and token (config or env for default account).`
+	};
+	const normalizedChannel = channel || account.channel;
+	if (!normalizedChannel) return {
+		ok: false,
+		messageId: generateMessageId(),
+		receipt: createTwitchSendReceipt({
+			messageId: "",
+			channel: normalizedChannel,
+			visible: false
+		}),
+		error: "No channel specified and no default channel in account config"
+	};
+	const deliveryChannel = normalizeTwitchChannel(normalizedChannel);
+	const cleanedText = stripMarkdown ? stripMarkdownForTwitch(text) : text;
+	if (!cleanedText) return {
+		ok: true,
+		messageId: "skipped",
+		receipt: createTwitchSendReceipt({
+			messageId: "skipped",
+			channel: deliveryChannel,
+			visible: false
+		})
+	};
+	const clientManager = getClientManager(resolvedAccountId);
+	if (!clientManager) return {
+		ok: false,
+		messageId: generateMessageId(),
+		receipt: createTwitchSendReceipt({
+			messageId: "",
+			channel: deliveryChannel,
+			visible: false
+		}),
+		error: `Client manager not found for account: ${resolvedAccountId}. Please start the Twitch gateway first.`
+	};
+	try {
+		const result = await clientManager.sendMessage(account, deliveryChannel, cleanedText, cfg, resolvedAccountId);
+		if (!result.ok) {
+			const messageId = result.messageId ?? generateMessageId();
+			return {
+				ok: false,
+				messageId,
+				receipt: createTwitchSendReceipt({
+					messageId,
+					channel: deliveryChannel,
+					visible: false
+				}),
+				error: result.error ?? "Send failed"
+			};
+		}
+		const messageId = result.messageId ?? generateMessageId();
+		return {
+			ok: true,
+			messageId,
+			receipt: createTwitchSendReceipt({
+				messageId,
+				channel: deliveryChannel,
+				visible: true
+			})
+		};
+	} catch (error) {
+		const errorMsg = formatErrorMessage(error);
+		const messageId = generateMessageId();
+		logger.error(`Failed to send message: ${errorMsg}`);
+		return {
+			ok: false,
+			messageId,
+			receipt: createTwitchSendReceipt({
+				messageId,
+				channel: deliveryChannel,
+				visible: false
+			}),
+			error: errorMsg
+		};
+	}
+}
+//#endregion
+//#region extensions/twitch/src/outbound.ts
+/**
+* Twitch outbound adapter for sending messages.
+*
+* Implements the ChannelOutboundAdapter interface for Twitch chat.
+* Supports text and media (URL) sending with markdown stripping and chunking.
+*/
+/**
+* Twitch outbound adapter.
+*
+* Handles sending text and media to Twitch channels with automatic
+* markdown stripping and message chunking.
+*/
+const twitchOutbound = {
+	/** Direct delivery mode - messages are sent immediately */
+	deliveryMode: "direct",
+	deliveryCapabilities: { durableFinal: {
+		text: true,
+		media: true,
+		messageSendingHooks: true
+	} },
+	/** Twitch chat message limit is 500 characters */
+	textChunkLimit: 500,
+	/** Word-boundary chunker with markdown stripping */
+	chunker: chunkTextForTwitch,
+	/**
+	* Resolve target from context.
+	*
+	* Handles target resolution with allowlist support for implicit/heartbeat modes.
+	* For explicit mode, accepts any valid channel name.
+	*
+	* @param params - Resolution parameters
+	* @returns Resolved target or error
+	*/
+	resolveTarget: ({ to, allowFrom, mode }) => {
+		const trimmed = to?.trim() ?? "";
+		const allowListRaw = (allowFrom ?? []).map((entry) => String(entry).trim()).filter(Boolean);
+		const hasWildcard = allowListRaw.includes("*");
+		const allowList = allowListRaw.filter((entry) => entry !== "*").map((entry) => normalizeTwitchChannel(entry)).filter((entry) => entry.length > 0);
+		if (trimmed) {
+			const normalizedTo = normalizeTwitchChannel(trimmed);
+			if (!normalizedTo) return {
+				ok: false,
+				error: missingTargetError("Twitch", "<channel-name>")
+			};
+			if (mode === "implicit" || mode === "heartbeat") {
+				if (hasWildcard || allowList.length === 0) return {
+					ok: true,
+					to: normalizedTo
+				};
+				if (allowList.includes(normalizedTo)) return {
+					ok: true,
+					to: normalizedTo
+				};
+				return {
+					ok: false,
+					error: missingTargetError("Twitch", "<channel-name>")
+				};
+			}
+			return {
+				ok: true,
+				to: normalizedTo
+			};
+		}
+		return {
+			ok: false,
+			error: missingTargetError("Twitch", "<channel-name>")
+		};
+	},
+	/**
+	* Send a text message to a Twitch channel.
+	*
+	* Strips markdown if enabled, validates account configuration,
+	* and sends the message via the Twitch client.
+	*
+	* @param params - Send parameters including target, text, and config
+	* @returns Delivery result with message ID and status
+	*
+	* @example
+	* const result = await twitchOutbound.sendText({
+	*   cfg: klawConfig,
+	*   to: "#mychannel",
+	*   text: "Hello Twitch!",
+	*   accountId: "default",
+	* });
+	*/
+	sendText: async (params) => {
+		const { cfg, to, text, accountId } = params;
+		if (params.signal?.aborted) throw new Error("Outbound delivery aborted");
+		const resolvedAccountId = accountId ?? resolveTwitchAccountContext(cfg).accountId;
+		const { account, availableAccountIds } = resolveTwitchAccountContext(cfg, resolvedAccountId);
+		if (!account) throw new Error(`Twitch account not found: ${resolvedAccountId}. Available accounts: ${availableAccountIds.join(", ") || "none"}`);
+		const channel = to || account.channel;
+		if (!channel) throw new Error("No channel specified and no default channel in account config");
+		const result = await sendMessageTwitchInternal(normalizeTwitchChannel(channel), text, cfg, resolvedAccountId, true, console);
+		if (!result.ok) throw new Error(result.error ?? "Send failed");
+		return {
+			channel: "twitch",
+			messageId: result.messageId,
+			receipt: result.receipt,
+			timestamp: Date.now()
+		};
+	},
+	/**
+	* Send media to a Twitch channel.
+	*
+	* Note: Twitch chat doesn't support direct media uploads.
+	* This sends the media URL as text instead.
+	*
+	* @param params - Send parameters including media URL
+	* @returns Delivery result with message ID and status
+	*
+	* @example
+	* const result = await twitchOutbound.sendMedia({
+	*   cfg: klawConfig,
+	*   to: "#mychannel",
+	*   text: "Check this out!",
+	*   mediaUrl: "https://example.com/image.png",
+	*   accountId: "default",
+	* });
+	*/
+	sendMedia: async (params) => {
+		const { text, mediaUrl } = params;
+		if (params.signal?.aborted) throw new Error("Outbound delivery aborted");
+		const message = mediaUrl ? `${text || ""} ${mediaUrl}`.trim() : text;
+		if (!twitchOutbound.sendText) throw new Error("sendText not implemented");
+		return twitchOutbound.sendText({
+			...params,
+			text: message
+		});
+	}
+};
+function toTwitchMessageSendResult(result, kind) {
+	const receipt = result.receipt ?? createMessageReceiptFromOutboundResults({
+		results: result.messageId ? [{
+			channel: "twitch",
+			messageId: result.messageId
+		}] : [],
+		kind
+	});
+	return {
+		messageId: result.messageId || receipt.primaryPlatformMessageId,
+		receipt
+	};
+}
+const twitchMessageAdapter = defineChannelMessageAdapter({
+	id: "twitch",
+	durableFinal: { capabilities: {
+		text: true,
+		media: true,
+		messageSendingHooks: true
+	} },
+	send: {
+		text: async (ctx) => {
+			if (!twitchOutbound.sendText) throw new Error("Twitch text sending is not available.");
+			return toTwitchMessageSendResult(await twitchOutbound.sendText(ctx), "text");
+		},
+		media: async (ctx) => {
+			if (!twitchOutbound.sendMedia) throw new Error("Twitch media sending is not available.");
+			return toTwitchMessageSendResult(await twitchOutbound.sendMedia(ctx), "media");
+		}
+	}
+});
+//#endregion
+//#region extensions/twitch/src/actions.ts
+/**
+* Twitch message actions adapter.
+*
+* Handles tool-based actions for Twitch, such as sending messages.
+*/
+/**
+* Create a tool result with error content.
+*/
+function errorResponse(error) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({
+				ok: false,
+				error
+			})
+		}],
+		details: { ok: false }
+	};
+}
+/**
+* Read a string parameter from action arguments.
+*
+* @param args - Action arguments
+* @param key - Parameter key
+* @param options - Options for reading the parameter
+* @returns The parameter value or undefined if not found
+*/
+function readStringParam(args, key, options = {}) {
+	const value = args[key];
+	if (value === void 0 || value === null) {
+		if (options.required) throw new Error(`Missing required parameter: ${key}`);
+		return;
+	}
+	if (typeof value === "string") return options.trim !== false ? value.trim() : value;
+	if (typeof value === "number" || typeof value === "boolean") {
+		const str = String(value);
+		return options.trim !== false ? str.trim() : str;
+	}
+	throw new Error(`Parameter ${key} must be a string, number, or boolean`);
+}
+/** Supported Twitch actions */
+const TWITCH_ACTIONS = new Set(["send"]);
+/**
+* Twitch message actions adapter.
+*/
+const twitchMessageActions = {
+	/**
+	* List available actions for this channel.
+	*/
+	describeMessageTool: () => ({ actions: [...TWITCH_ACTIONS] }),
+	/**
+	* Check if an action is supported.
+	*/
+	supportsAction: ({ action }) => TWITCH_ACTIONS.has(action),
+	/**
+	* Extract tool send parameters from action arguments.
+	*
+	* Parses and validates the "to" and "message" parameters for sending.
+	*
+	* @param params - Arguments from the tool call
+	* @returns Parsed send parameters or null if invalid
+	*
+	* @example
+	* const result = twitchMessageActions.extractToolSend!({
+	*   args: { to: "#mychannel", message: "Hello!" }
+	* });
+	* // Returns: { to: "#mychannel", message: "Hello!" }
+	*/
+	extractToolSend: ({ args }) => {
+		try {
+			const to = readStringParam(args, "to", { required: true });
+			const message = readStringParam(args, "message", { required: true });
+			if (!to || !message) return null;
+			return {
+				to,
+				message
+			};
+		} catch {
+			return null;
+		}
+	},
+	/**
+	* Handle an action execution.
+	*
+	* Processes the "send" action to send messages to Twitch.
+	*
+	* @param ctx - Action context including action type, parameters, and config
+	* @returns Tool result with content or null if action not supported
+	*
+	* @example
+	* const result = await twitchMessageActions.handleAction!({
+	*   action: "send",
+	*   params: { message: "Hello Twitch!", to: "#mychannel" },
+	*   cfg: klawConfig,
+	*   accountId: "default",
+	* });
+	*/
+	handleAction: async (ctx) => {
+		if (ctx.action !== "send") return {
+			content: [{
+				type: "text",
+				text: "Unsupported action"
+			}],
+			details: {
+				ok: false,
+				error: "Unsupported action"
+			}
+		};
+		const message = readStringParam(ctx.params, "message", { required: true });
+		const to = readStringParam(ctx.params, "to", { required: false });
+		const accountId = ctx.accountId ?? resolveTwitchAccountContext(ctx.cfg).accountId;
+		const { account, availableAccountIds } = resolveTwitchAccountContext(ctx.cfg, accountId);
+		if (!account) return errorResponse(`Account not found: ${accountId}. Available accounts: ${availableAccountIds.join(", ") || "none"}`);
+		const targetChannel = to || account.channel;
+		if (!targetChannel) return errorResponse("No channel specified and no default channel in account config");
+		if (!twitchOutbound.sendText) return errorResponse("sendText not implemented");
+		try {
+			const result = await twitchOutbound.sendText({
+				cfg: ctx.cfg,
+				to: targetChannel,
+				text: message ?? "",
+				accountId
+			});
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result)
+				}],
+				details: { ok: true }
+			};
+		} catch (error) {
+			return errorResponse(formatErrorMessage(error));
+		}
+	}
+};
+//#endregion
+//#region extensions/twitch/src/config-schema.ts
+/**
+* Twitch user roles that can be allowed to interact with the bot
+*/
+const TwitchRoleSchema = z.enum([
+	"moderator",
+	"owner",
+	"vip",
+	"subscriber",
+	"all"
+]);
+const TwitchAccountShape = {
+	/** Twitch username */
+	username: z.string(),
+	/** Twitch OAuth access token (requires chat:read and chat:write scopes) */
+	accessToken: z.string(),
+	/** Twitch client ID (from Twitch Developer Portal or twitchtokengenerator.com) */
+	clientId: z.string().optional(),
+	/** Channel name to join */
+	channel: z.string().min(1),
+	/** Enable this account */
+	enabled: z.boolean().optional(),
+	/** Allowlist of Twitch user IDs who can interact with the bot (use IDs for safety, not usernames) */
+	allowFrom: z.array(z.string()).optional(),
+	/** Roles allowed to interact with the bot (e.g., ["moderator", "vip", "subscriber"]) */
+	allowedRoles: z.array(TwitchRoleSchema).optional(),
+	/** Require @mention to trigger bot responses */
+	requireMention: z.boolean().optional(),
+	/** Outbound response prefix override for this channel/account. */
+	responsePrefix: z.string().optional(),
+	/** Twitch client secret (required for token refresh via RefreshingAuthProvider) */
+	clientSecret: z.string().optional(),
+	/** Refresh token (required for automatic token refresh) */
+	refreshToken: z.string().optional(),
+	/** Token expiry time in seconds (optional, for token refresh tracking) */
+	expiresIn: z.number().nullable().optional(),
+	/** Timestamp when token was obtained (optional, for token refresh tracking) */
+	obtainmentTimestamp: z.number().optional()
+};
+/**
+* Twitch account configuration schema
+*/
+const TwitchAccountSchema = z.object(TwitchAccountShape);
+/**
+* Base configuration properties shared by both single and multi-account modes
+*/
+const TwitchConfigBaseShape = {
+	name: z.string().optional(),
+	enabled: z.boolean().optional(),
+	markdown: MarkdownConfigSchema.optional(),
+	defaultAccount: z.string().optional()
+};
+/**
+* Simplified single-account configuration schema
+*
+* Use this for single-account setups. Properties are at the top level,
+* creating an implicit "default" account.
+*/
+const SimplifiedSchema = z.object({
+	...TwitchConfigBaseShape,
+	...TwitchAccountShape
+});
+/**
+* Multi-account configuration schema
+*
+* Use this for multi-account setups. Each key is an account ID (e.g., "default", "secondary").
+*/
+const MultiAccountSchema = z.object({
+	...TwitchConfigBaseShape,
+	/** Per-account configuration (for multi-account setups) */
+	accounts: z.record(z.string(), TwitchAccountSchema)
+}).refine((val) => Object.keys(val.accounts || {}).length > 0, { message: "accounts must contain at least one entry" });
+/**
+* Twitch plugin configuration schema
+*
+* Supports two mutually exclusive patterns:
+* 1. Simplified single-account: username, accessToken, clientId, channel at top level
+* 2. Multi-account: accounts object with named account configs
+*
+* The union ensures clear discrimination between the two modes.
+*/
+const TwitchConfigSchema = z.union([SimplifiedSchema, MultiAccountSchema]);
+//#endregion
+//#region extensions/twitch/src/probe.ts
+/**
+* Probe a Twitch account to verify the connection is working
+*
+* This tests the Twitch OAuth token by attempting to connect
+* to the chat server and verify the bot's username.
+*/
+async function probeTwitch(account, timeoutMs) {
+	const started = Date.now();
+	if (!account.accessToken || !account.username) return {
+		ok: false,
+		error: "missing credentials (accessToken, username)",
+		username: account.username,
+		elapsedMs: Date.now() - started
+	};
+	const rawToken = normalizeToken(account.accessToken.trim());
+	let client;
+	try {
+		client = new ChatClient({ authProvider: new StaticAuthProvider(account.clientId ?? "", rawToken) });
+		const connectionPromise = new Promise((resolve, reject) => {
+			let settled = false;
+			let connectListener;
+			let disconnectListener;
+			let authFailListener;
+			const cleanup = () => {
+				if (settled) return;
+				settled = true;
+				connectListener?.unbind();
+				disconnectListener?.unbind();
+				authFailListener?.unbind();
+			};
+			connectListener = client?.onConnect(() => {
+				cleanup();
+				resolve();
+			});
+			disconnectListener = client?.onDisconnect((_manually, reason) => {
+				cleanup();
+				reject(reason || /* @__PURE__ */ new Error("Disconnected"));
+			});
+			authFailListener = client?.onAuthenticationFailure(() => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error("Authentication failed"));
+			});
+		});
+		let timeoutHandle;
+		const timeout = new Promise((_, reject) => {
+			timeoutHandle = setTimeout(() => reject(/* @__PURE__ */ new Error(`timeout after ${timeoutMs}ms`)), timeoutMs);
+		});
+		client.connect();
+		try {
+			await Promise.race([connectionPromise, timeout]);
+		} finally {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+		}
+		client.quit();
+		client = void 0;
+		return {
+			ok: true,
+			connected: true,
+			username: account.username,
+			channel: account.channel,
+			elapsedMs: Date.now() - started
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: formatErrorMessage(error),
+			username: account.username,
+			channel: account.channel,
+			elapsedMs: Date.now() - started
+		};
+	} finally {
+		if (client) try {
+			client.quit();
+		} catch {}
+	}
+}
+//#endregion
+//#region extensions/twitch/src/resolver.ts
+/**
+* Twitch resolver adapter for channel/user name resolution.
+*
+* This module implements the ChannelResolverAdapter interface to resolve
+* Twitch usernames to user IDs via the Twitch Helix API.
+*/
+/**
+* Normalize a Twitch username - strip @ prefix and convert to lowercase
+*/
+function normalizeUsername(input) {
+	const trimmed = input.trim();
+	if (trimmed.startsWith("@")) return normalizeLowercaseStringOrEmpty(trimmed.slice(1));
+	return normalizeLowercaseStringOrEmpty(trimmed);
+}
+/**
+* Create a logger that includes the Twitch prefix
+*/
+function createLogger(logger) {
+	return {
+		info: (msg) => logger?.info(msg),
+		warn: (msg) => logger?.warn(msg),
+		error: (msg) => logger?.error(msg),
+		debug: (msg) => logger?.debug?.(msg) ?? (() => {})
+	};
+}
+/**
+* Resolve Twitch usernames to user IDs via the Helix API
+*
+* @param inputs - Array of usernames or user IDs to resolve
+* @param account - Twitch account configuration with auth credentials
+* @param kind - Type of target to resolve ("user" or "group")
+* @param logger - Optional logger
+* @returns Promise resolving to array of ChannelResolveResult
+*/
+async function resolveTwitchTargets(inputs, account, _kind, logger) {
+	const log = createLogger(logger);
+	if (!account.clientId || !account.accessToken) {
+		log.error("Missing Twitch client ID or accessToken");
+		return inputs.map((input) => ({
+			input,
+			resolved: false,
+			note: "missing Twitch credentials"
+		}));
+	}
+	const normalizedToken = normalizeToken(account.accessToken);
+	const apiClient = new ApiClient({ authProvider: new StaticAuthProvider(account.clientId, normalizedToken) });
+	const results = [];
+	for (const input of inputs) {
+		const normalized = normalizeUsername(input);
+		if (!normalized) {
+			results.push({
+				input,
+				resolved: false,
+				note: "empty input"
+			});
+			continue;
+		}
+		const looksLikeUserId = /^\d+$/.test(normalized);
+		try {
+			if (looksLikeUserId) {
+				const user = await apiClient.users.getUserById(normalized);
+				if (user) {
+					results.push({
+						input,
+						resolved: true,
+						id: user.id,
+						name: user.name
+					});
+					log.debug?.(`Resolved user ID ${normalized} -> ${user.name}`);
+				} else {
+					results.push({
+						input,
+						resolved: false,
+						note: "user ID not found"
+					});
+					log.warn(`User ID ${normalized} not found`);
+				}
+			} else {
+				const user = await apiClient.users.getUserByName(normalized);
+				if (user) {
+					results.push({
+						input,
+						resolved: true,
+						id: user.id,
+						name: user.name,
+						note: user.displayName !== user.name ? `display: ${user.displayName}` : void 0
+					});
+					log.debug?.(`Resolved username ${normalized} -> ${user.id} (${user.name})`);
+				} else {
+					results.push({
+						input,
+						resolved: false,
+						note: "username not found"
+					});
+					log.warn(`Username ${normalized} not found`);
+				}
+			}
+		} catch (error) {
+			const errorMessage = formatErrorMessage(error);
+			results.push({
+				input,
+				resolved: false,
+				note: `API error: ${errorMessage}`
+			});
+			log.error(`Failed to resolve ${input}: ${errorMessage}`);
+		}
+	}
+	return results;
+}
+//#endregion
+//#region extensions/twitch/src/status.ts
+/**
+* Collect status issues for Twitch accounts.
+*
+* Analyzes account snapshots and detects configuration problems,
+* authentication issues, and other potential problems.
+*
+* @param accounts - Array of account snapshots to analyze
+* @param getCfg - Optional function to get full config for additional checks
+* @returns Array of detected status issues
+*
+* @example
+* const issues = collectTwitchStatusIssues(accountSnapshots);
+* if (issues.length > 0) {
+*   console.warn("Twitch configuration issues detected:");
+*   issues.forEach(issue => console.warn(`- ${issue.message}`));
+* }
+*/
+function collectTwitchStatusIssues(accounts, getCfg) {
+	const issues = [];
+	for (const entry of accounts) {
+		const accountId = entry.accountId;
+		if (!accountId) continue;
+		let account = null;
+		let cfg;
+		if (getCfg) try {
+			cfg = getCfg();
+			account = getAccountConfig(cfg, accountId);
+		} catch {}
+		if (!entry.configured) {
+			issues.push({
+				channel: "twitch",
+				accountId,
+				kind: "config",
+				message: "Twitch account is not properly configured",
+				fix: "Add required fields: username, accessToken, and clientId to your account configuration"
+			});
+			continue;
+		}
+		if (entry.enabled === false) {
+			issues.push({
+				channel: "twitch",
+				accountId,
+				kind: "config",
+				message: "Twitch account is disabled",
+				fix: "Set enabled: true in your account configuration to enable this account"
+			});
+			continue;
+		}
+		if (account && account.username && account.accessToken && !account.clientId) issues.push({
+			channel: "twitch",
+			accountId,
+			kind: "config",
+			message: "Twitch client ID is required",
+			fix: "Add clientId to your Twitch account configuration (from Twitch Developer Portal)"
+		});
+		const tokenResolution = cfg ? resolveTwitchToken(cfg, { accountId }) : {
+			token: "",
+			source: "none"
+		};
+		if (account && isAccountConfigured(account, tokenResolution.token)) {
+			if (account.accessToken?.startsWith("oauth:")) issues.push({
+				channel: "twitch",
+				accountId,
+				kind: "config",
+				message: "Token contains 'oauth:' prefix (will be stripped)",
+				fix: "The 'oauth:' prefix is optional. You can use just the token value, or keep it as-is (it will be normalized automatically)."
+			});
+			if (account.clientSecret && !account.refreshToken) issues.push({
+				channel: "twitch",
+				accountId,
+				kind: "config",
+				message: "clientSecret provided without refreshToken",
+				fix: "For automatic token refresh, provide both clientSecret and refreshToken. Otherwise, clientSecret is not needed."
+			});
+			if (account.allowFrom && account.allowFrom.length === 0) issues.push({
+				channel: "twitch",
+				accountId,
+				kind: "config",
+				message: "allowFrom is configured but empty",
+				fix: "Either add user IDs to allowFrom, remove the allowFrom field, or use allowedRoles instead."
+			});
+			if (account.allowedRoles?.includes("all") && account.allowFrom && account.allowFrom.length > 0) issues.push({
+				channel: "twitch",
+				accountId,
+				kind: "intent",
+				message: "allowedRoles is set to 'all' but allowFrom is also configured",
+				fix: "When allowedRoles is 'all', the allowFrom list is not needed. Remove allowFrom or set allowedRoles to specific roles."
+			});
+		}
+		if (entry.lastError) issues.push({
+			channel: "twitch",
+			accountId,
+			kind: "runtime",
+			message: `Last error: ${entry.lastError}`,
+			fix: "Check your token validity and network connection. Ensure the bot has the required OAuth scopes."
+		});
+		if (entry.configured && !entry.running && !entry.lastStartAt && !entry.lastInboundAt && !entry.lastOutboundAt) issues.push({
+			channel: "twitch",
+			accountId,
+			kind: "runtime",
+			message: "Account has never connected successfully",
+			fix: "Start the Twitch gateway to begin receiving messages. Check logs for connection errors."
+		});
+		if (entry.running && entry.lastStartAt) {
+			const daysSinceStart = (Date.now() - entry.lastStartAt) / (1e3 * 60 * 60 * 24);
+			if (daysSinceStart > 7) issues.push({
+				channel: "twitch",
+				accountId,
+				kind: "runtime",
+				message: `Connection has been running for ${Math.floor(daysSinceStart)} days`,
+				fix: "Consider restarting the connection periodically to refresh the connection. Twitch tokens may expire after long periods."
+			});
+		}
+	}
+	return issues;
+}
+//#endregion
+//#region extensions/twitch/src/plugin.ts
+/**
+* Twitch channel plugin for Klaw.
+*
+* Main plugin export combining all adapters (outbound, actions, status, gateway).
+* This is the primary entry point for the Twitch channel integration.
+*/
+/**
+* Twitch channel plugin.
+*
+* Implements the ChannelPlugin interface to provide Twitch chat integration
+* for Klaw. Supports message sending, receiving, access control, and
+* status monitoring.
+*/
+const twitchPlugin = createChatChannelPlugin({
+	pairing: {
+		idLabel: "twitchUserId",
+		normalizeAllowEntry: createPairingPrefixStripper(/^(twitch:)?user:?/i),
+		notifyApproval: createLoggedPairingApprovalNotifier(({ id }) => `Pairing approved for user ${id} (notification sent via chat if possible)`, console.warn)
+	},
+	outbound: twitchOutbound,
+	base: {
+		id: "twitch",
+		meta: {
+			id: "twitch",
+			label: "Twitch",
+			selectionLabel: "Twitch (Chat)",
+			docsPath: "/channels/twitch",
+			blurb: "Twitch chat integration",
+			aliases: ["twitch-chat"]
+		},
+		setup: twitchSetupAdapter,
+		setupWizard: twitchSetupWizard,
+		capabilities: { chatTypes: ["group"] },
+		message: twitchMessageAdapter,
+		configSchema: buildChannelConfigSchema(TwitchConfigSchema),
+		config: {
+			listAccountIds: (cfg) => listAccountIds(cfg),
+			resolveAccount: (cfg, accountId) => {
+				const resolvedAccountId = accountId ?? resolveDefaultTwitchAccountId(cfg);
+				const account = getAccountConfig(cfg, resolvedAccountId);
+				if (!account) return {
+					accountId: resolvedAccountId,
+					channel: "",
+					username: "",
+					accessToken: "",
+					clientId: "",
+					enabled: false
+				};
+				return {
+					accountId: resolvedAccountId,
+					...account
+				};
+			},
+			defaultAccountId: (cfg) => resolveDefaultTwitchAccountId(cfg),
+			isConfigured: (_account, cfg) => resolveTwitchAccountContext(cfg).configured,
+			isEnabled: (account) => account?.enabled !== false,
+			describeAccount: (account) => account ? describeAccountSnapshot({
+				account,
+				configured: isAccountConfigured(account, account.accessToken)
+			}) : {
+				accountId: DEFAULT_ACCOUNT_ID,
+				enabled: false,
+				configured: false
+			}
+		},
+		actions: twitchMessageActions,
+		resolver: { resolveTargets: async ({ cfg, accountId, inputs, kind, runtime }) => {
+			const account = getAccountConfig(cfg, accountId ?? resolveDefaultTwitchAccountId(cfg));
+			if (!account) return inputs.map((input) => ({
+				input,
+				resolved: false,
+				note: "account not configured"
+			}));
+			return await resolveTwitchTargets(inputs, account, kind, {
+				info: (msg) => runtime.log(msg),
+				warn: (msg) => runtime.log(msg),
+				error: (msg) => runtime.error(msg),
+				debug: (msg) => runtime.log(msg)
+			});
+		} },
+		status: createComputedAccountStatusAdapter({
+			defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+			buildChannelSummary: ({ snapshot }) => buildPassiveProbedChannelStatusSummary(snapshot),
+			probeAccount: async ({ account, timeoutMs }) => await probeTwitch(account, timeoutMs),
+			collectStatusIssues: collectTwitchStatusIssues,
+			resolveAccountSnapshot: ({ account, cfg }) => {
+				const resolvedAccountId = account.accountId || resolveTwitchSnapshotAccountId(cfg, account);
+				const { configured } = resolveTwitchAccountContext(cfg, resolvedAccountId);
+				return {
+					accountId: resolvedAccountId,
+					enabled: account.enabled !== false,
+					configured
+				};
+			}
+		}),
+		gateway: {
+			startAccount: async (ctx) => {
+				const account = ctx.account;
+				const accountId = ctx.accountId;
+				ctx.setStatus?.({
+					accountId,
+					running: true,
+					lastStartAt: Date.now(),
+					lastError: null
+				});
+				ctx.log?.info(`Starting Twitch connection for ${account.username}`);
+				await runStoppablePassiveMonitor({
+					abortSignal: ctx.abortSignal,
+					start: async () => {
+						const { monitorTwitchProvider } = await import("./monitor-j1GtQVBd.js");
+						return monitorTwitchProvider({
+							account,
+							accountId,
+							config: ctx.cfg,
+							runtime: ctx.runtime,
+							abortSignal: ctx.abortSignal
+						});
+					}
+				});
+			},
+			stopAccount: async (ctx) => {
+				const account = ctx.account;
+				const accountId = ctx.accountId;
+				await removeClientManager(accountId);
+				ctx.setStatus?.({
+					accountId,
+					running: false,
+					lastStopAt: Date.now()
+				});
+				ctx.log?.info(`Stopped Twitch connection for ${account.username}`);
+			}
+		}
+	}
+});
+//#endregion
+export { stripMarkdownForTwitch as n, getOrCreateClientManager as r, twitchPlugin as t };