@openclaw/irc 2026.7.2-beta.3 → 2026.7.2-beta.4

package/dist/api.js

@@ -1,3 +1,3 @@
-import { g as resolveIrcAccount, h as resolveDefaultIrcAccountId, m as listIrcAccountIds, n as ircSetupWizard, p as listEnabledIrcAccounts, r as ircSetupAdapter, t as ircPlugin } from "./channel-BC0q2_Tg.js";
+import { _ as resolveIrcAccount, g as resolveDefaultIrcAccountId, h as listIrcAccountIds, m as listEnabledIrcAccounts, n as ircSetupWizard, r as ircSetupAdapter, t as ircPlugin } from "./channel-BuxKUEja.js";
 import { n as setIrcRuntime } from "./runtime-xy-FcjJC.js";
 export { ircPlugin, ircSetupAdapter, ircSetupWizard, listEnabledIrcAccounts, listIrcAccountIds, resolveDefaultIrcAccountId, resolveIrcAccount, setIrcRuntime };

package/dist/{channel-BC0q2_Tg.js → channel-BuxKUEja.js}

@@ -15,16 +15,16 @@ import { parseStrictPositiveInteger } from "openclaw/plugin-sdk/number-runtime";
 import { tryReadSecretFileSync } from "openclaw/plugin-sdk/secret-file-runtime";
 import { normalizeResolvedSecretInputString } from "openclaw/plugin-sdk/secret-input";
 import { normalizeLowercaseStringOrEmpty, normalizeOptionalLowercaseString, normalizeOptionalString, normalizeStringEntries, normalizeStringifiedOptionalString, uniqueStrings } from "openclaw/plugin-sdk/string-coerce-runtime";
-import { createAccountStatusSink, createMessageReceiptFromOutboundResults, defineChannelMessageAdapter, sanitizeForPlainText } from "openclaw/plugin-sdk/channel-outbound";
+import { createAccountStatusSink, createMessageReceiptFromOutboundResults, defineChannelMessageAdapter, runPassiveAccountLifecycle, sanitizeForPlainText } from "openclaw/plugin-sdk/channel-outbound";
 import { PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk/channel-status";
 import { chunkTextForOutbound, convertMarkdownTables, sanitizeAssistantVisibleText } from "openclaw/plugin-sdk/text-chunking";
-import { runStoppablePassiveMonitor } from "openclaw/plugin-sdk/extension-shared";
 import { resolveMarkdownTableMode } from "openclaw/plugin-sdk/markdown-table-runtime";
 import { requireRuntimeConfig } from "openclaw/plugin-sdk/plugin-config-runtime";
 import net from "node:net";
 import tls from "node:tls";
 import { withTimeout } from "openclaw/plugin-sdk/security-runtime";
 import { randomUUID } from "node:crypto";
+import { defineChannelSetupContract } from "openclaw/plugin-sdk/channel-setup";
 import { DEFAULT_ACCOUNT_ID as DEFAULT_ACCOUNT_ID$1, normalizeAccountId as normalizeAccountId$1 } from "openclaw/plugin-sdk/routing";
 import { applyAccountNameToChannelSection, createAllowFromSection, createPromptParsedAllowFromForAccount, createSetupInputPresenceValidator, createSetupTranslator, createStandardChannelSetupStatus, createTopLevelChannelAllowFromSetter, createTopLevelChannelDmPolicySetter, formatDocsLink, patchScopedAccountConfig, setSetupChannelEnabled } from "openclaw/plugin-sdk/setup";
 //#region extensions/irc/src/accounts.ts
@@ -202,7 +202,7 @@ const collectIrcMutableAllowlistWarnings = createDangerousNameMatchingMutableAll
 });
 //#endregion
 //#region extensions/irc/src/gateway.ts
-const loadIrcChannelRuntime$1 = createLazyRuntimeModule(() => import("./channel-runtime-DBNGrI_Y.js"));
+const loadIrcChannelRuntime$1 = createLazyRuntimeModule(() => import("./channel-runtime-BrNJqIB_.js"));
 async function startIrcGatewayAccount(ctx) {
 	const account = ctx.account;
 	const statusSink = createAccountStatusSink({
@@ -212,7 +212,7 @@ async function startIrcGatewayAccount(ctx) {
 	if (!account.configured) throw new Error(`IRC is not configured for account "${account.accountId}" (need host and nick in channels.irc).`);
 	ctx.log?.info?.(`[${account.accountId}] starting IRC provider (${account.host}:${account.port}${account.tls ? " tls" : ""})`);
 	const { monitorIrcProvider } = await loadIrcChannelRuntime$1();
-	await runStoppablePassiveMonitor({
+	await runPassiveAccountLifecycle({
 		abortSignal: ctx.abortSignal,
 		start: async () => await monitorIrcProvider({
 			accountId: account.accountId,
@@ -220,7 +220,10 @@ async function startIrcGatewayAccount(ctx) {
 			runtime: ctx.runtime,
 			abortSignal: ctx.abortSignal,
 			statusSink
-		})
+		}),
+		stop: async (monitor) => {
+			await monitor.stop();
+		}
 	});
 }
 //#endregion
@@ -554,7 +557,7 @@ async function connectIrcClient(options) {
 			if (line.command === "PRIVMSG") {
 				const targetParam = line.params[0];
 				const target = targetParam ? targetParam.trim() : "";
-				const text = line.trailing != null ? line.trailing : "";
+				const text = line.trailing ?? line.params[1] ?? "";
 				const prefix = parseIrcPrefix(line.prefix);
 				const senderNick = prefix.nick ? prefix.nick.trim() : "";
 				if (!target || !senderNick || !text.trim()) continue;
@@ -562,6 +565,7 @@ async function connectIrcClient(options) {
 					senderNick,
 					senderUser: prefix.user ? prefix.user.trim() : void 0,
 					senderHost: prefix.host ? prefix.host.trim() : void 0,
+					connectedNick: currentNick,
 					target,
 					text,
 					rawLine
@@ -939,6 +943,7 @@ function setIrcGroupAccess(cfg, accountId, policy, entries, normalizeGroupEntry)
 	});
 }
 const ircSetupAdapter = {
+	singleAccountKeysToMove: ["password"],
 	resolveAccountId: ({ accountId }) => normalizeAccountId$1(accountId),
 	applyAccountName: ({ cfg, accountId, name }) => applyAccountNameToChannelSection({
 		cfg,
@@ -975,6 +980,75 @@ const ircSetupAdapter = {
 		});
 	}
 };
+const ircSetupContract = defineChannelSetupContract({
+	fields: {
+		host: {
+			kind: "string",
+			cli: {
+				flags: "--host <host>",
+				description: "IRC server host"
+			}
+		},
+		port: {
+			kind: "string",
+			cli: {
+				flags: "--port <port>",
+				description: "IRC server port"
+			}
+		},
+		tls: {
+			kind: "boolean",
+			cli: {
+				flags: "--tls",
+				description: "Use TLS for IRC"
+			}
+		},
+		nick: {
+			kind: "string",
+			cli: {
+				flags: "--nick <nick>",
+				description: "IRC nickname"
+			}
+		},
+		username: {
+			kind: "string",
+			cli: {
+				flags: "--username <name>",
+				description: "IRC username"
+			}
+		},
+		realname: {
+			kind: "string",
+			cli: {
+				flags: "--realname <name>",
+				description: "IRC real name"
+			}
+		},
+		channels: {
+			kind: "string-list",
+			cli: {
+				flags: "--channels <names>",
+				description: "IRC channels"
+			}
+		},
+		password: {
+			kind: "string",
+			sensitive: true,
+			cli: {
+				flags: "--password <password>",
+				description: "IRC server password"
+			}
+		},
+		useEnv: {
+			kind: "boolean",
+			cli: {
+				flags: "--use-env",
+				description: "Use IRC environment configuration"
+			}
+		}
+	},
+	legacyAdapter: ircSetupAdapter
+});
 //#endregion
 //#region extensions/irc/src/setup-surface.ts
 const t = createSetupTranslator();
@@ -1340,7 +1414,7 @@ const meta = {
 	systemImage: "number",
 	markdownCapable: true
 };
-const loadIrcChannelRuntime = createLazyRuntimeModule(() => import("./channel-runtime-DBNGrI_Y.js"));
+const loadIrcChannelRuntime = createLazyRuntimeModule(() => import("./channel-runtime-BrNJqIB_.js"));
 function normalizePairingTarget(raw) {
 	const normalized = normalizeIrcAllowEntry(raw);
 	if (!normalized) return "";
@@ -1413,6 +1487,7 @@ const ircPlugin = createChatChannelPlugin({
 			quickstartAllowFrom: true
 		},
 		setup: ircSetupAdapter,
+		setupContract: ircSetupContract,
 		setupWizard: ircSetupWizard,
 		capabilities: {
 			chatTypes: ["direct", "group"],
@@ -1590,4 +1665,4 @@ const ircPlugin = createChatChannelPlugin({
 	}
 });
 //#endregion
-export { resolveIrcGroupRequireMention as a, isChannelTarget as c, connectIrcClient as d, makeIrcMessageId as f, resolveIrcAccount as g, resolveDefaultIrcAccountId as h, resolveIrcGroupMatch as i, normalizeIrcAllowEntry as l, listIrcAccountIds as m, ircSetupWizard as n, sendMessageIrc as o, listEnabledIrcAccounts as p, ircSetupAdapter as r, buildIrcAllowlistCandidates as s, ircPlugin as t, buildIrcConnectOptions as u };
+export { resolveIrcAccount as _, resolveIrcGroupRequireMention as a, isChannelTarget as c, connectIrcClient as d, parseIrcLine as f, resolveDefaultIrcAccountId as g, listIrcAccountIds as h, resolveIrcGroupMatch as i, normalizeIrcAllowEntry as l, listEnabledIrcAccounts as m, ircSetupWizard as n, sendMessageIrc as o, parseIrcPrefix as p, ircSetupAdapter as r, buildIrcAllowlistCandidates as s, ircPlugin as t, buildIrcConnectOptions as u };

package/dist/channel-plugin-api.js

@@ -1,2 +1,2 @@
-import { t as ircPlugin } from "./channel-BC0q2_Tg.js";
+import { t as ircPlugin } from "./channel-BuxKUEja.js";
 export { ircPlugin };

package/dist/{channel-runtime-DBNGrI_Y.js → channel-runtime-BrNJqIB_.js}

@@ -1,7 +1,8 @@
-import { a as resolveIrcGroupRequireMention, c as isChannelTarget, d as connectIrcClient, f as makeIrcMessageId, g as resolveIrcAccount, i as resolveIrcGroupMatch, l as normalizeIrcAllowEntry, o as sendMessageIrc, s as buildIrcAllowlistCandidates, u as buildIrcConnectOptions } from "./channel-BC0q2_Tg.js";
+import { _ as resolveIrcAccount, a as resolveIrcGroupRequireMention, c as isChannelTarget, d as connectIrcClient, f as parseIrcLine, i as resolveIrcGroupMatch, l as normalizeIrcAllowEntry, o as sendMessageIrc, p as parseIrcPrefix, s as buildIrcAllowlistCandidates, u as buildIrcConnectOptions } from "./channel-BuxKUEja.js";
 import { t as getIrcRuntime } from "./runtime-xy-FcjJC.js";
 import { normalizeLowercaseStringOrEmpty, normalizeOptionalString, normalizeStringEntries } from "openclaw/plugin-sdk/string-coerce-runtime";
-import { resolveChannelStreamingBlockEnabled } from "openclaw/plugin-sdk/channel-outbound";
+import { bindIngressLifecycleToReplyOptions, createChannelIngressMonitor, resolveChannelStreamingBlockEnabled } from "openclaw/plugin-sdk/channel-outbound";
+import { randomUUID } from "node:crypto";
 import { resolveLoggerBackedRuntime } from "openclaw/plugin-sdk/extension-shared";
 import { buildChannelInboundEventContext, logInboundDrop, resolveChannelInboundRouteEnvelope } from "openclaw/plugin-sdk/channel-inbound";
 import { channelIngressRoutes, createChannelIngressResolver, defineStableChannelIngressIdentity } from "openclaw/plugin-sdk/channel-ingress-runtime";
@@ -120,7 +121,7 @@ async function deliverIrcReply(params) {
 	});
 }
 async function handleIrcInbound(params) {
-	const { message, account, config, runtime, connectedNick, statusSink } = params;
+	const { message, account, config, runtime, connectedNick, statusSink, turnAdoptionLifecycle } = params;
 	const core = getIrcRuntime();
 	const pairing = createChannelPairingController({
 		core,
@@ -128,7 +129,11 @@ async function handleIrcInbound(params) {
 		accountId: account.accountId
 	});
 	const rawBody = message.text?.trim() ?? "";
-	if (!rawBody) return;
+	if (!rawBody) return { kind: "completed" };
+	if (turnAdoptionLifecycle?.abortSignal.aborted) return {
+		kind: "failed-retryable",
+		error: turnAdoptionLifecycle.abortSignal.reason
+	};
 	statusSink?.({ lastInboundAt: message.timestamp });
 	const senderDisplay = message.senderHost ? `${message.senderNick}!${message.senderUser ?? "?"}@${message.senderHost}` : message.senderNick;
 	const allowNameMatching = isDangerousNameMatchingEnabled(account.config);
@@ -228,11 +233,11 @@ async function handleIrcInbound(params) {
 			}
 		});
 		runtime.log?.(`irc: drop DM sender ${senderDisplay} (dmPolicy=${dmPolicy})`);
-		return;
+		return { kind: "completed" };
 	}
 	if (access.ingress.admission === "skip") {
 		runtime.log?.(`irc: drop channel ${message.target} (missing-mention)`);
-		return;
+		return { kind: "completed" };
 	}
 	if (access.ingress.admission !== "dispatch") {
 		if (message.isGroup && access.ingress.decisiveGateId === "command" && access.commandAccess.shouldBlockControlCommand) {
@@ -242,14 +247,18 @@ async function handleIrcInbound(params) {
 				reason: "control command (unauthorized)",
 				target: senderDisplay
 			});
-			return;
+			return { kind: "completed" };
 		}
 		if (message.isGroup) if (access.routeAccess.reason === "channel_not_allowlisted") runtime.log?.(`irc: drop channel ${message.target} (not allowlisted)`);
 		else if (access.routeAccess.reason === "channel_disabled") runtime.log?.(`irc: drop channel ${message.target} (disabled)`);
 		else runtime.log?.(`irc: drop group sender ${senderDisplay} (policy=${groupPolicy})`);
 		else runtime.log?.(`irc: drop DM sender ${senderDisplay} (dmPolicy=${dmPolicy})`);
-		return;
+		return { kind: "completed" };
 	}
+	if (turnAdoptionLifecycle?.abortSignal.aborted) return {
+		kind: "failed-retryable",
+		error: turnAdoptionLifecycle.abortSignal.reason
+	};
 	const channelTarget = message.target.startsWith("#") || message.target.startsWith("&") ? message.target : `#${message.target}`;
 	const peerId = message.isGroup ? channelTarget : message.senderNick;
 	const { route, buildEnvelope } = resolveChannelInboundRouteEnvelope({
@@ -313,6 +322,22 @@ async function handleIrcInbound(params) {
 			GroupSystemPrompt: message.isGroup ? groupSystemPrompt : void 0
 		}
 	});
+	const ingressState = { handoff: "none" };
+	const trackedIngressLifecycle = turnAdoptionLifecycle ? {
+		...turnAdoptionLifecycle,
+		onAdopted: async () => {
+			ingressState.handoff = "adopted";
+			await turnAdoptionLifecycle.onAdopted();
+		},
+		onDeferred: () => {
+			ingressState.handoff = "deferred";
+			turnAdoptionLifecycle.onDeferred();
+		},
+		onAbandoned: async () => {
+			ingressState.handoff = "abandoned";
+			await turnAdoptionLifecycle.onAbandoned();
+		}
+	} : void 0;
 	await core.channel.inbound.dispatch({
 		cfg: config,
 		channel: CHANNEL_ID,
@@ -339,6 +364,7 @@ async function handleIrcInbound(params) {
 		},
 		replyPipeline: {},
 		replyOptions: {
+			...trackedIngressLifecycle ? bindIngressLifecycleToReplyOptions(trackedIngressLifecycle) : {},
 			skillFilter: groupMatch.groupConfig?.skills,
 			disableBlockStreaming: typeof blockStreamingEnabled === "boolean" ? !blockStreamingEnabled : void 0
 		},
@@ -346,23 +372,162 @@ async function handleIrcInbound(params) {
 			runtime.error?.(`irc: failed updating session meta: ${String(err)}`);
 		} }
 	});
+	if (turnAdoptionLifecycle?.abortSignal.aborted && ingressState.handoff === "none") return {
+		kind: "failed-retryable",
+		error: turnAdoptionLifecycle.abortSignal.reason
+	};
+	if (turnAdoptionLifecycle && ingressState.handoff === "none") {
+		await turnAdoptionLifecycle.onAdopted();
+		ingressState.handoff = "adopted";
+	}
+	return ingressState.handoff === "deferred" || ingressState.handoff === "abandoned" ? { kind: "deferred" } : { kind: "completed" };
 }
 //#endregion
-//#region extensions/irc/src/monitor.ts
-const IRC_MONITOR_RECONNECT_DELAY_MS = 1e3;
-function resolveIrcInboundTarget(params) {
-	const rawTarget = params.target;
-	if (isChannelTarget(rawTarget)) return {
-		isGroup: true,
-		target: rawTarget,
-		rawTarget
+//#region extensions/irc/src/irc-ingress.ts
+const IRC_INGRESS_PAYLOAD_VERSION = 1;
+const IRC_INGRESS_POLL_INTERVAL_MS = 1e3;
+const IRC_INGRESS_PRUNE_INTERVAL_MS = 3600 * 1e3;
+const IRC_INGRESS_TOMBSTONE_TTL_MS = 720 * 60 * 60 * 1e3;
+const IRC_INGRESS_TOMBSTONE_MAX_ENTRIES = 1e3;
+var IrcIngressPayloadError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "IrcIngressPayloadError";
+	}
+};
+function inspectRawPrivmsg(rawLine) {
+	const line = parseIrcLine(rawLine);
+	if (!line || line.command !== "PRIVMSG") throw new IrcIngressPayloadError("IRC ingress row is not a PRIVMSG line.");
+	const rawTarget = line.params[0]?.trim() ?? "";
+	const text = line.trailing ?? line.params[1] ?? "";
+	const prefix = parseIrcPrefix(line.prefix);
+	const senderNick = prefix.nick?.trim() ?? "";
+	if (!rawTarget || !senderNick || !text.trim()) throw new IrcIngressPayloadError("IRC PRIVMSG line is missing target, sender, or text.");
+	const isGroup = isChannelTarget(rawTarget);
+	const target = isGroup ? rawTarget : senderNick;
+	const lanePeer = normalizeLowercaseStringOrEmpty(target);
+	return {
+		laneKey: `${isGroup ? "channel" : "direct"}:${lanePeer}`,
+		message: {
+			target,
+			rawTarget,
+			senderNick,
+			senderUser: prefix.user?.trim() || void 0,
+			senderHost: prefix.host?.trim() || void 0,
+			text,
+			isGroup
+		}
+	};
+}
+function decodeIrcIngressPayload(payload, claimedId) {
+	if (!payload || typeof payload !== "object" || Array.isArray(payload) || typeof payload.eventId !== "string" || !Number.isSafeInteger(payload.receivedAt) || (payload.receivedAt ?? 0) <= 0 || typeof payload.connectionEpoch !== "string" || !payload.connectionEpoch?.trim() || typeof payload.connectedNick !== "string" || !payload.connectedNick?.trim() || typeof payload.rawLine !== "string") throw new IrcIngressPayloadError(`IRC ingress row ${claimedId} has invalid metadata.`);
+	const validPayload = payload;
+	return {
+		version: validPayload.version,
+		body: {
+			eventId: validPayload.eventId,
+			receivedAt: validPayload.receivedAt,
+			connectionEpoch: validPayload.connectionEpoch,
+			connectedNick: validPayload.connectedNick,
+			rawLine: validPayload.rawLine
+		}
 	};
+}
+function inspectIrcIngress(raw, phase) {
+	try {
+		return {
+			eventId: raw.eventId,
+			laneKey: inspectRawPrivmsg(raw.rawLine).laneKey
+		};
+	} catch (error) {
+		if (phase === "admission" && error instanceof IrcIngressPayloadError) return {
+			eventId: raw.eventId,
+			laneKey: `invalid:${raw.eventId}`
+		};
+		throw error;
+	}
+}
+function resolveIrcIngressNonRetryableFailure(error) {
+	return error instanceof IrcIngressPayloadError ? {
+		reason: "invalid-event",
+		message: error.message
+	} : null;
+}
+function createIrcIngressMonitor(options) {
+	const monitor = createChannelIngressMonitor({
+		queue: options.queue ?? (() => getIrcRuntime().state.openChannelIngressQueue({ accountId: options.accountId })),
+		inspect: (raw, context) => inspectIrcIngress(raw, context.phase),
+		payload: {
+			version: IRC_INGRESS_PAYLOAD_VERSION,
+			serialize: (raw) => raw,
+			deserialize: (body) => body,
+			encode: ({ body }) => ({
+				version: IRC_INGRESS_PAYLOAD_VERSION,
+				...body
+			}),
+			decode: (payload, { claim }) => decodeIrcIngressPayload(payload, claim.id),
+			createClaimError: (_kind, claim) => new IrcIngressPayloadError(`IRC ingress row ${claim.id} has invalid metadata.`)
+		},
+		deliver: (raw, lifecycle, claim) => {
+			const message = {
+				...inspectRawPrivmsg(raw.rawLine).message,
+				messageId: claim.id,
+				timestamp: raw.receivedAt
+			};
+			return options.dispatch(message, lifecycle, {
+				connectedNick: raw.connectedNick.trim(),
+				connectionEpoch: raw.connectionEpoch.trim()
+			});
+		},
+		pollIntervalMs: options.pollIntervalMs ?? IRC_INGRESS_POLL_INTERVAL_MS,
+		retention: {
+			pruneIntervalMs: IRC_INGRESS_PRUNE_INTERVAL_MS,
+			completedTtlMs: IRC_INGRESS_TOMBSTONE_TTL_MS,
+			completedMaxEntries: IRC_INGRESS_TOMBSTONE_MAX_ENTRIES,
+			failedTtlMs: IRC_INGRESS_TOMBSTONE_TTL_MS,
+			failedMaxEntries: IRC_INGRESS_TOMBSTONE_MAX_ENTRIES
+		},
+		drain: {
+			resolveNonRetryableFailure: resolveIrcIngressNonRetryableFailure,
+			...options.adoptionStallTimeoutMs === void 0 ? {} : { adoptionStallTimeoutMs: options.adoptionStallTimeoutMs },
+			onLog: (message) => options.runtime.log?.(`irc ${message}`)
+		},
+		createStoppedError: () => /* @__PURE__ */ new Error("IRC ingress is stopped."),
+		onError: (error) => options.runtime.error?.(`irc ingress drain failed: ${String(error)}`)
+	});
 	return {
-		isGroup: false,
-		target: params.senderNick.trim() || rawTarget,
-		rawTarget
+		openConnection: (connectionEpoch = randomUUID()) => {
+			const epoch = connectionEpoch.trim();
+			if (!epoch) throw new Error("IRC ingress connection epoch is required.");
+			let sequence = 0;
+			return {
+				connectionEpoch: epoch,
+				accept: (rawLine, connectedNick) => {
+					if (monitor.isStopped()) return Promise.reject(/* @__PURE__ */ new Error("IRC ingress is stopped."));
+					sequence += 1;
+					const eventId = `local:${epoch}:${String(sequence).padStart(12, "0")}`;
+					const receivedAt = Date.now();
+					const normalizedNick = connectedNick.trim();
+					if (!normalizedNick) return Promise.reject(/* @__PURE__ */ new Error("IRC ingress connected nickname is required."));
+					return monitor.admit({
+						eventId,
+						rawLine,
+						receivedAt,
+						connectionEpoch: epoch,
+						connectedNick: normalizedNick
+					}, { receivedAt }).then(() => void 0);
+				}
+			};
+		},
+		start: monitor.start,
+		pause: monitor.pause,
+		stop: monitor.stop,
+		waitForIdle: monitor.waitForIdle
 	};
 }
+//#endregion
+//#region extensions/irc/src/monitor.ts
+const IRC_MONITOR_RECONNECT_DELAY_MS = 1e3;
 async function monitorIrcProvider(opts) {
 	const core = getIrcRuntime();
 	const cfg = opts.config ?? core.config.current();
@@ -377,6 +542,8 @@ async function monitorIrcProvider(opts) {
 		accountId: account.accountId
 	});
 	let client = null;
+	let activeConnectionEpoch = null;
+	let ingressPause = Promise.resolve();
 	let reconnectTimer = null;
 	let stopped = false;
 	const monitorAbort = new AbortController();
@@ -389,6 +556,48 @@ async function monitorIrcProvider(opts) {
 			removeAbortListener = () => opts.abortSignal?.removeEventListener("abort", forwardAbort);
 		}
 	}
+	const ingress = createIrcIngressMonitor({
+		accountId: account.accountId,
+		runtime,
+		...opts.ingressQueue ? { queue: opts.ingressQueue } : {},
+		dispatch: async (message, turnAdoptionLifecycle, context) => {
+			const activeClient = client;
+			if (!activeClient || stopped || monitorAbort.signal.aborted) return {
+				kind: "failed-retryable",
+				error: /* @__PURE__ */ new Error("IRC transport disconnected before ingress dispatch.")
+			};
+			if (normalizeLowercaseStringOrEmpty(message.senderNick) === normalizeLowercaseStringOrEmpty(context.connectedNick)) return { kind: "completed" };
+			if (!message.isGroup && context.connectionEpoch !== activeConnectionEpoch) {
+				logger.warn?.(`[${account.accountId}] dropping replayed IRC DM after the connection changed`);
+				return { kind: "completed" };
+			}
+			if (opts.onMessage) {
+				await opts.onMessage(message, activeClient);
+				return { kind: "completed" };
+			}
+			return await handleIrcInbound({
+				message,
+				account,
+				config: cfg,
+				runtime,
+				connectedNick: context.connectedNick,
+				turnAdoptionLifecycle,
+				sendReply: async (target, text) => {
+					const replyClient = client;
+					if (!replyClient || !replyClient.isReady() || stopped || monitorAbort.signal.aborted) throw new Error("IRC transport disconnected before reply send.");
+					if (!message.isGroup && context.connectionEpoch !== activeConnectionEpoch) throw new Error("IRC connection changed before private reply send.");
+					replyClient.sendPrivmsg(target, text);
+					opts.statusSink?.({ lastOutboundAt: Date.now() });
+					core.channel.activity.record({
+						channel: "irc",
+						accountId: account.accountId,
+						direction: "outbound"
+					});
+				},
+				statusSink: opts.statusSink
+			});
+		}
+	});
 	function scheduleReconnect() {
 		if (stopped || monitorAbort.signal.aborted || reconnectTimer) return;
 		reconnectTimer = setTimeout(() => {
@@ -403,6 +612,7 @@ async function monitorIrcProvider(opts) {
 	}
 	async function connect() {
 		if (stopped || monitorAbort.signal.aborted) return;
+		const ingressConnection = ingress.openConnection();
 		const nextClient = await connectIrcClient(buildIrcConnectOptions(account, {
 			channels: account.config.channels,
 			abortSignal: monitorAbort.signal,
@@ -417,54 +627,20 @@ async function monitorIrcProvider(opts) {
 			},
 			onDisconnect: () => {
 				if (stopped || monitorAbort.signal.aborted) return;
+				ingressPause = ingress.pause();
+				if (activeConnectionEpoch === ingressConnection.connectionEpoch) activeConnectionEpoch = null;
 				client = null;
 				logger.warn?.(`[${account.accountId}] IRC connection closed; reconnecting in ${IRC_MONITOR_RECONNECT_DELAY_MS}ms`);
 				scheduleReconnect();
 			},
 			onPrivmsg: async (event) => {
-				if (!client) return;
-				if (normalizeLowercaseStringOrEmpty(event.senderNick) === normalizeLowercaseStringOrEmpty(client.nick)) return;
-				const inboundTarget = resolveIrcInboundTarget({
-					target: event.target,
-					senderNick: event.senderNick
-				});
-				const message = {
-					messageId: makeIrcMessageId(),
-					target: inboundTarget.target,
-					rawTarget: inboundTarget.rawTarget,
-					senderNick: event.senderNick,
-					senderUser: event.senderUser,
-					senderHost: event.senderHost,
-					text: event.text,
-					timestamp: Date.now(),
-					isGroup: inboundTarget.isGroup
-				};
+				await ingressConnection.accept(event.rawLine, event.connectedNick);
+				if (normalizeLowercaseStringOrEmpty(event.senderNick) === normalizeLowercaseStringOrEmpty(event.connectedNick)) return;
 				core.channel.activity.record({
 					channel: "irc",
 					accountId: account.accountId,
 					direction: "inbound",
-					at: message.timestamp
-				});
-				if (opts.onMessage) {
-					await opts.onMessage(message, client);
-					return;
-				}
-				await handleIrcInbound({
-					message,
-					account,
-					config: cfg,
-					runtime,
-					connectedNick: client.nick,
-					sendReply: async (target, text) => {
-						client?.sendPrivmsg(target, text);
-						opts.statusSink?.({ lastOutboundAt: Date.now() });
-						core.channel.activity.record({
-							channel: "irc",
-							accountId: account.accountId,
-							direction: "outbound"
-						});
-					},
-					statusSink: opts.statusSink
+					at: Date.now()
 				});
 			}
 		}));
@@ -473,20 +649,40 @@ async function monitorIrcProvider(opts) {
 			return;
 		}
 		client = nextClient;
+		activeConnectionEpoch = ingressConnection.connectionEpoch;
+		await ingressPause;
+		if (client !== nextClient || !nextClient.isReady()) {
+			if (activeConnectionEpoch === ingressConnection.connectionEpoch) activeConnectionEpoch = null;
+			return;
+		}
+		ingress.start();
 		logger.info(`[${account.accountId}] connected to ${account.host}:${account.port}${account.tls ? " (tls)" : ""} as ${nextClient.nick}`);
 	}
-	await connect();
-	return { stop: () => {
-		stopped = true;
+	try {
+		await connect();
+	} catch (error) {
 		removeAbortListener?.();
 		removeAbortListener = null;
-		if (!monitorAbort.signal.aborted) monitorAbort.abort();
-		if (reconnectTimer) {
-			clearTimeout(reconnectTimer);
-			reconnectTimer = null;
-		}
-		client?.quit("shutdown");
-		client = null;
+		await ingress.stop();
+		throw error;
+	}
+	let stopTask;
+	return { stop: () => {
+		stopTask ??= (async () => {
+			stopped = true;
+			removeAbortListener?.();
+			removeAbortListener = null;
+			if (!monitorAbort.signal.aborted) monitorAbort.abort();
+			if (reconnectTimer) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = null;
+			}
+			client?.quit("shutdown");
+			client = null;
+			activeConnectionEpoch = null;
+			await ingress.stop();
+		})();
+		return stopTask;
 	} };
 }
 //#endregion

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@openclaw/irc",
-  "version": "2026.7.2-beta.3",
+  "version": "2026.7.2-beta.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@openclaw/irc",
-      "version": "2026.7.2-beta.3",
+      "version": "2026.7.2-beta.4",
       "dependencies": {
         "zod": "4.4.3"
       }

package/openclaw.plugin.json

@@ -6,20 +6,6 @@
   "channels": [
     "irc"
   ],
-  "channelEnvVars": {
-    "irc": [
-      "IRC_HOST",
-      "IRC_PORT",
-      "IRC_TLS",
-      "IRC_NICK",
-      "IRC_USERNAME",
-      "IRC_REALNAME",
-      "IRC_PASSWORD",
-      "IRC_CHANNELS",
-      "IRC_NICKSERV_PASSWORD",
-      "IRC_NICKSERV_REGISTER_EMAIL"
-    ]
-  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/irc",
-  "version": "2026.7.2-beta.3",
+  "version": "2026.7.2-beta.4",
   "description": "OpenClaw IRC channel plugin",
   "type": "module",
   "openclaw": {
@@ -15,8 +15,19 @@
       "allowInvalidConfigRecovery": true
     },
     "setupEntry": "./dist/setup-entry.js",
+    "setupFeatures": {
+      "configPromotion": true
+    },
     "channel": {
       "id": "irc",
+      "configuredState": {
+        "env": {
+          "allOf": [
+            "IRC_HOST",
+            "IRC_NICK"
+          ]
+        }
+      },
       "label": "IRC",
       "selectionLabel": "IRC (Server + Nick)",
       "detailLabel": "IRC",
@@ -27,20 +38,89 @@
         "internet-relay-chat"
       ],
       "systemImage": "network",
-      "configuredState": {
-        "env": {
-          "allOf": [
-            "IRC_HOST",
-            "IRC_NICK"
-          ]
-        }
+      "setup": {
+        "fields": [
+          {
+            "key": "host",
+            "kind": "string",
+            "cli": {
+              "flags": "--host <host>",
+              "description": "IRC server host"
+            }
+          },
+          {
+            "key": "port",
+            "kind": "string",
+            "cli": {
+              "flags": "--port <port>",
+              "description": "IRC server port"
+            }
+          },
+          {
+            "key": "tls",
+            "kind": "boolean",
+            "cli": {
+              "flags": "--tls",
+              "description": "Use TLS for IRC"
+            }
+          },
+          {
+            "key": "nick",
+            "kind": "string",
+            "cli": {
+              "flags": "--nick <nick>",
+              "description": "IRC nickname"
+            }
+          },
+          {
+            "key": "username",
+            "kind": "string",
+            "cli": {
+              "flags": "--username <name>",
+              "description": "IRC username"
+            }
+          },
+          {
+            "key": "realname",
+            "kind": "string",
+            "cli": {
+              "flags": "--realname <name>",
+              "description": "IRC real name"
+            }
+          },
+          {
+            "key": "channels",
+            "kind": "string-list",
+            "cli": {
+              "flags": "--channels <names>",
+              "description": "IRC channels"
+            }
+          },
+          {
+            "key": "password",
+            "kind": "string",
+            "sensitive": true,
+            "cli": {
+              "flags": "--password <password>",
+              "description": "IRC server password"
+            }
+          },
+          {
+            "key": "useEnv",
+            "kind": "boolean",
+            "cli": {
+              "flags": "--use-env",
+              "description": "Use IRC environment configuration"
+            }
+          }
+        ]
       }
     },
     "compat": {
-      "pluginApi": ">=2026.7.2-beta.3"
+      "pluginApi": ">=2026.7.2-beta.4"
     },
     "build": {
-      "openclawVersion": "2026.7.2-beta.3",
+      "openclawVersion": "2026.7.2-beta.4",
       "bundledDist": false
     },
     "release": {
@@ -66,7 +146,7 @@
     "README.md"
   ],
   "peerDependencies": {
-    "openclaw": ">=2026.7.2-beta.3"
+    "openclaw": ">=2026.7.2-beta.4"
   },
   "peerDependenciesMeta": {
     "openclaw": {