@poolzin/pool-bot 2026.2.11 → 2026.2.18

package/extensions/irc/src/inbound.ts

@@ -0,0 +1,334 @@
+import {
+  createReplyPrefixOptions,
+  logInboundDrop,
+  resolveControlCommandGate,
+  type PoolBotConfig,
+  type RuntimeEnv,
+} from "poolbot/plugin-sdk";
+import type { ResolvedIrcAccount } from "./accounts.js";
+import { normalizeIrcAllowlist, resolveIrcAllowlistMatch } from "./normalize.js";
+import {
+  resolveIrcMentionGate,
+  resolveIrcGroupAccessGate,
+  resolveIrcGroupMatch,
+  resolveIrcGroupSenderAllowed,
+  resolveIrcRequireMention,
+} from "./policy.js";
+import { getIrcRuntime } from "./runtime.js";
+import { sendMessageIrc } from "./send.js";
+import type { CoreConfig, IrcInboundMessage } from "./types.js";
+
+const CHANNEL_ID = "irc" as const;
+
+const escapeIrcRegexLiteral = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+async function deliverIrcReply(params: {
+  payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string; replyToId?: string };
+  target: string;
+  accountId: string;
+  sendReply?: (target: string, text: string, replyToId?: string) => Promise<void>;
+  statusSink?: (patch: { lastOutboundAt?: number }) => void;
+}) {
+  const text = params.payload.text ?? "";
+  const mediaList = params.payload.mediaUrls?.length
+    ? params.payload.mediaUrls
+    : params.payload.mediaUrl
+      ? [params.payload.mediaUrl]
+      : [];
+
+  if (!text.trim() && mediaList.length === 0) {
+    return;
+  }
+
+  const mediaBlock = mediaList.length
+    ? mediaList.map((url) => `Attachment: ${url}`).join("\n")
+    : "";
+  const combined = text.trim()
+    ? mediaBlock
+      ? `${text.trim()}\n\n${mediaBlock}`
+      : text.trim()
+    : mediaBlock;
+
+  if (params.sendReply) {
+    await params.sendReply(params.target, combined, params.payload.replyToId);
+  } else {
+    await sendMessageIrc(params.target, combined, {
+      accountId: params.accountId,
+      replyTo: params.payload.replyToId,
+    });
+  }
+  params.statusSink?.({ lastOutboundAt: Date.now() });
+}
+
+export async function handleIrcInbound(params: {
+  message: IrcInboundMessage;
+  account: ResolvedIrcAccount;
+  config: CoreConfig;
+  runtime: RuntimeEnv;
+  connectedNick?: string;
+  sendReply?: (target: string, text: string, replyToId?: string) => Promise<void>;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+}): Promise<void> {
+  const { message, account, config, runtime, connectedNick, statusSink } = params;
+  const core = getIrcRuntime();
+
+  const rawBody = message.text?.trim() ?? "";
+  if (!rawBody) {
+    return;
+  }
+
+  statusSink?.({ lastInboundAt: message.timestamp });
+
+  const senderDisplay = message.senderHost
+    ? `${message.senderNick}!${message.senderUser ?? "?"}@${message.senderHost}`
+    : message.senderNick;
+
+  const dmPolicy = account.config.dmPolicy ?? "pairing";
+  const defaultGroupPolicy = config.channels?.defaults?.groupPolicy;
+  const groupPolicy = account.config.groupPolicy ?? defaultGroupPolicy ?? "allowlist";
+
+  const configAllowFrom = normalizeIrcAllowlist(account.config.allowFrom);
+  const configGroupAllowFrom = normalizeIrcAllowlist(account.config.groupAllowFrom);
+  const storeAllowFrom = await core.channel.pairing.readAllowFromStore(CHANNEL_ID).catch(() => []);
+  const storeAllowList = normalizeIrcAllowlist(storeAllowFrom);
+
+  const groupMatch = resolveIrcGroupMatch({
+    groups: account.config.groups,
+    target: message.target,
+  });
+
+  if (message.isGroup) {
+    const groupAccess = resolveIrcGroupAccessGate({ groupPolicy, groupMatch });
+    if (!groupAccess.allowed) {
+      runtime.log?.(`irc: drop channel ${message.target} (${groupAccess.reason})`);
+      return;
+    }
+  }
+
+  const directGroupAllowFrom = normalizeIrcAllowlist(groupMatch.groupConfig?.allowFrom);
+  const wildcardGroupAllowFrom = normalizeIrcAllowlist(groupMatch.wildcardConfig?.allowFrom);
+  const groupAllowFrom =
+    directGroupAllowFrom.length > 0 ? directGroupAllowFrom : wildcardGroupAllowFrom;
+
+  const effectiveAllowFrom = [...configAllowFrom, ...storeAllowList].filter(Boolean);
+  const effectiveGroupAllowFrom = [...configGroupAllowFrom, ...storeAllowList].filter(Boolean);
+
+  const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+    cfg: config as PoolBotConfig,
+    surface: CHANNEL_ID,
+  });
+  const useAccessGroups = config.commands?.useAccessGroups !== false;
+  const senderAllowedForCommands = resolveIrcAllowlistMatch({
+    allowFrom: message.isGroup ? effectiveGroupAllowFrom : effectiveAllowFrom,
+    message,
+  }).allowed;
+  const hasControlCommand = core.channel.text.hasControlCommand(rawBody, config as PoolBotConfig);
+  const commandGate = resolveControlCommandGate({
+    useAccessGroups,
+    authorizers: [
+      {
+        configured: (message.isGroup ? effectiveGroupAllowFrom : effectiveAllowFrom).length > 0,
+        allowed: senderAllowedForCommands,
+      },
+    ],
+    allowTextCommands,
+    hasControlCommand,
+  });
+  const commandAuthorized = commandGate.commandAuthorized;
+
+  if (message.isGroup) {
+    const senderAllowed = resolveIrcGroupSenderAllowed({
+      groupPolicy,
+      message,
+      outerAllowFrom: effectiveGroupAllowFrom,
+      innerAllowFrom: groupAllowFrom,
+    });
+    if (!senderAllowed) {
+      runtime.log?.(`irc: drop group sender ${senderDisplay} (policy=${groupPolicy})`);
+      return;
+    }
+  } else {
+    if (dmPolicy === "disabled") {
+      runtime.log?.(`irc: drop DM sender=${senderDisplay} (dmPolicy=disabled)`);
+      return;
+    }
+    if (dmPolicy !== "open") {
+      const dmAllowed = resolveIrcAllowlistMatch({
+        allowFrom: effectiveAllowFrom,
+        message,
+      }).allowed;
+      if (!dmAllowed) {
+        if (dmPolicy === "pairing") {
+          const { code, created } = await core.channel.pairing.upsertPairingRequest({
+            channel: CHANNEL_ID,
+            id: senderDisplay.toLowerCase(),
+            meta: { name: message.senderNick || undefined },
+          });
+          if (created) {
+            try {
+              const reply = core.channel.pairing.buildPairingReply({
+                channel: CHANNEL_ID,
+                idLine: `Your IRC id: ${senderDisplay}`,
+                code,
+              });
+              await deliverIrcReply({
+                payload: { text: reply },
+                target: message.senderNick,
+                accountId: account.accountId,
+                sendReply: params.sendReply,
+                statusSink,
+              });
+            } catch (err) {
+              runtime.error?.(`irc: pairing reply failed for ${senderDisplay}: ${String(err)}`);
+            }
+          }
+        }
+        runtime.log?.(`irc: drop DM sender ${senderDisplay} (dmPolicy=${dmPolicy})`);
+        return;
+      }
+    }
+  }
+
+  if (message.isGroup && commandGate.shouldBlock) {
+    logInboundDrop({
+      log: (line) => runtime.log?.(line),
+      channel: CHANNEL_ID,
+      reason: "control command (unauthorized)",
+      target: senderDisplay,
+    });
+    return;
+  }
+
+  const mentionRegexes = core.channel.mentions.buildMentionRegexes(config as PoolBotConfig);
+  const mentionNick = connectedNick?.trim() || account.nick;
+  const explicitMentionRegex = mentionNick
+    ? new RegExp(`\\b${escapeIrcRegexLiteral(mentionNick)}\\b[:,]?`, "i")
+    : null;
+  const wasMentioned =
+    core.channel.mentions.matchesMentionPatterns(rawBody, mentionRegexes) ||
+    (explicitMentionRegex ? explicitMentionRegex.test(rawBody) : false);
+
+  const requireMention = message.isGroup
+    ? resolveIrcRequireMention({
+        groupConfig: groupMatch.groupConfig,
+        wildcardConfig: groupMatch.wildcardConfig,
+      })
+    : false;
+
+  const mentionGate = resolveIrcMentionGate({
+    isGroup: message.isGroup,
+    requireMention,
+    wasMentioned,
+    hasControlCommand,
+    allowTextCommands,
+    commandAuthorized,
+  });
+  if (mentionGate.shouldSkip) {
+    runtime.log?.(`irc: drop channel ${message.target} (${mentionGate.reason})`);
+    return;
+  }
+
+  const peerId = message.isGroup ? message.target : message.senderNick;
+  const route = core.channel.routing.resolveAgentRoute({
+    cfg: config as PoolBotConfig,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+    peer: {
+      kind: message.isGroup ? "group" : "direct",
+      id: peerId,
+    },
+  });
+
+  const fromLabel = message.isGroup ? message.target : senderDisplay;
+  const storePath = core.channel.session.resolveStorePath(config.session?.store, {
+    agentId: route.agentId,
+  });
+  const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(config as PoolBotConfig);
+  const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+    storePath,
+    sessionKey: route.sessionKey,
+  });
+  const body = core.channel.reply.formatAgentEnvelope({
+    channel: "IRC",
+    from: fromLabel,
+    timestamp: message.timestamp,
+    previousTimestamp,
+    envelope: envelopeOptions,
+    body: rawBody,
+  });
+
+  const groupSystemPrompt = groupMatch.groupConfig?.systemPrompt?.trim() || undefined;
+
+  const ctxPayload = core.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: rawBody,
+    CommandBody: rawBody,
+    From: message.isGroup ? `irc:channel:${message.target}` : `irc:${senderDisplay}`,
+    To: `irc:${peerId}`,
+    SessionKey: route.sessionKey,
+    AccountId: route.accountId,
+    ChatType: message.isGroup ? "group" : "direct",
+    ConversationLabel: fromLabel,
+    SenderName: message.senderNick || undefined,
+    SenderId: senderDisplay,
+    GroupSubject: message.isGroup ? message.target : undefined,
+    GroupSystemPrompt: message.isGroup ? groupSystemPrompt : undefined,
+    Provider: CHANNEL_ID,
+    Surface: CHANNEL_ID,
+    WasMentioned: message.isGroup ? wasMentioned : undefined,
+    MessageSid: message.messageId,
+    Timestamp: message.timestamp,
+    OriginatingChannel: CHANNEL_ID,
+    OriginatingTo: `irc:${peerId}`,
+    CommandAuthorized: commandAuthorized,
+  });
+
+  await core.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (err) => {
+      runtime.error?.(`irc: failed updating session meta: ${String(err)}`);
+    },
+  });
+
+  const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+    cfg: config as PoolBotConfig,
+    agentId: route.agentId,
+    channel: CHANNEL_ID,
+    accountId: account.accountId,
+  });
+
+  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: config as PoolBotConfig,
+    dispatcherOptions: {
+      ...prefixOptions,
+      deliver: async (payload) => {
+        await deliverIrcReply({
+          payload: payload as {
+            text?: string;
+            mediaUrls?: string[];
+            mediaUrl?: string;
+            replyToId?: string;
+          },
+          target: peerId,
+          accountId: account.accountId,
+          sendReply: params.sendReply,
+          statusSink,
+        });
+      },
+      onError: (err, info) => {
+        runtime.error?.(`irc ${info.kind} reply failed: ${String(err)}`);
+      },
+    },
+    replyOptions: {
+      skillFilter: groupMatch.groupConfig?.skills,
+      onModelSelected,
+      disableBlockStreaming:
+        typeof account.config.blockStreaming === "boolean"
+          ? !account.config.blockStreaming
+          : undefined,
+    },
+  });
+}

package/extensions/irc/src/monitor.ts

@@ -0,0 +1,147 @@
+import type { RuntimeEnv } from "poolbot/plugin-sdk";
+import { resolveIrcAccount } from "./accounts.js";
+import { connectIrcClient, type IrcClient } from "./client.js";
+import { buildIrcConnectOptions } from "./connect-options.js";
+import { handleIrcInbound } from "./inbound.js";
+import { isChannelTarget } from "./normalize.js";
+import { makeIrcMessageId } from "./protocol.js";
+import { getIrcRuntime } from "./runtime.js";
+import type { CoreConfig, IrcInboundMessage } from "./types.js";
+
+export type IrcMonitorOptions = {
+  accountId?: string;
+  config?: CoreConfig;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  onMessage?: (message: IrcInboundMessage, client: IrcClient) => void | Promise<void>;
+};
+
+export function resolveIrcInboundTarget(params: { target: string; senderNick: string }): {
+  isGroup: boolean;
+  target: string;
+  rawTarget: string;
+} {
+  const rawTarget = params.target;
+  const isGroup = isChannelTarget(rawTarget);
+  if (isGroup) {
+    return { isGroup: true, target: rawTarget, rawTarget };
+  }
+  const senderNick = params.senderNick.trim();
+  return { isGroup: false, target: senderNick || rawTarget, rawTarget };
+}
+
+export async function monitorIrcProvider(opts: IrcMonitorOptions): Promise<{ stop: () => void }> {
+  const core = getIrcRuntime();
+  const cfg = opts.config ?? (core.config.loadConfig() as CoreConfig);
+  const account = resolveIrcAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+
+  const runtime: RuntimeEnv = opts.runtime ?? {
+    log: (...args: unknown[]) => core.logging.getChildLogger().info(args.map(String).join(" ")),
+    error: (...args: unknown[]) => core.logging.getChildLogger().error(args.map(String).join(" ")),
+    exit: () => {
+      throw new Error("Runtime exit not available");
+    },
+  };
+
+  if (!account.configured) {
+    throw new Error(
+      `IRC is not configured for account "${account.accountId}" (need host and nick in channels.irc).`,
+    );
+  }
+
+  const logger = core.logging.getChildLogger({
+    channel: "irc",
+    accountId: account.accountId,
+  });
+
+  let client: IrcClient | null = null;
+
+  client = await connectIrcClient(
+    buildIrcConnectOptions(account, {
+      channels: account.config.channels,
+      abortSignal: opts.abortSignal,
+      onLine: (line) => {
+        if (core.logging.shouldLogVerbose()) {
+          logger.debug?.(`[${account.accountId}] << ${line}`);
+        }
+      },
+      onNotice: (text, target) => {
+        if (core.logging.shouldLogVerbose()) {
+          logger.debug?.(`[${account.accountId}] notice ${target ?? ""}: ${text}`);
+        }
+      },
+      onError: (error) => {
+        logger.error(`[${account.accountId}] IRC error: ${error.message}`);
+      },
+      onPrivmsg: async (event) => {
+        if (!client) {
+          return;
+        }
+        if (event.senderNick.toLowerCase() === client.nick.toLowerCase()) {
+          return;
+        }
+
+        const inboundTarget = resolveIrcInboundTarget({
+          target: event.target,
+          senderNick: event.senderNick,
+        });
+        const message: IrcInboundMessage = {
+          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,
+        };
+
+        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,
+        });
+      },
+    }),
+  );
+
+  logger.info(
+    `[${account.accountId}] connected to ${account.host}:${account.port}${account.tls ? " (tls)" : ""} as ${client.nick}`,
+  );
+
+  return {
+    stop: () => {
+      client?.quit("shutdown");
+      client = null;
+    },
+  };
+}

package/extensions/irc/src/normalize.ts

@@ -0,0 +1,117 @@
+import { hasIrcControlChars } from "./control-chars.js";
+import type { IrcInboundMessage } from "./types.js";
+
+const IRC_TARGET_PATTERN = /^[^\s:]+$/u;
+
+export function isChannelTarget(target: string): boolean {
+  return target.startsWith("#") || target.startsWith("&");
+}
+
+export function normalizeIrcMessagingTarget(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  let target = trimmed;
+  const lowered = target.toLowerCase();
+  if (lowered.startsWith("irc:")) {
+    target = target.slice("irc:".length).trim();
+  }
+  if (target.toLowerCase().startsWith("channel:")) {
+    target = target.slice("channel:".length).trim();
+    if (!target.startsWith("#") && !target.startsWith("&")) {
+      target = `#${target}`;
+    }
+  }
+  if (target.toLowerCase().startsWith("user:")) {
+    target = target.slice("user:".length).trim();
+  }
+  if (!target || !looksLikeIrcTargetId(target)) {
+    return undefined;
+  }
+  return target;
+}
+
+export function looksLikeIrcTargetId(raw: string): boolean {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return false;
+  }
+  if (hasIrcControlChars(trimmed)) {
+    return false;
+  }
+  return IRC_TARGET_PATTERN.test(trimmed);
+}
+
+export function normalizeIrcAllowEntry(raw: string): string {
+  let value = raw.trim().toLowerCase();
+  if (!value) {
+    return "";
+  }
+  if (value.startsWith("irc:")) {
+    value = value.slice("irc:".length);
+  }
+  if (value.startsWith("user:")) {
+    value = value.slice("user:".length);
+  }
+  return value.trim();
+}
+
+export function normalizeIrcAllowlist(entries?: Array<string | number>): string[] {
+  return (entries ?? []).map((entry) => normalizeIrcAllowEntry(String(entry))).filter(Boolean);
+}
+
+export function formatIrcSenderId(message: IrcInboundMessage): string {
+  const base = message.senderNick.trim();
+  const user = message.senderUser?.trim();
+  const host = message.senderHost?.trim();
+  if (user && host) {
+    return `${base}!${user}@${host}`;
+  }
+  if (user) {
+    return `${base}!${user}`;
+  }
+  if (host) {
+    return `${base}@${host}`;
+  }
+  return base;
+}
+
+export function buildIrcAllowlistCandidates(message: IrcInboundMessage): string[] {
+  const nick = message.senderNick.trim().toLowerCase();
+  const user = message.senderUser?.trim().toLowerCase();
+  const host = message.senderHost?.trim().toLowerCase();
+  const candidates = new Set<string>();
+  if (nick) {
+    candidates.add(nick);
+  }
+  if (nick && user) {
+    candidates.add(`${nick}!${user}`);
+  }
+  if (nick && host) {
+    candidates.add(`${nick}@${host}`);
+  }
+  if (nick && user && host) {
+    candidates.add(`${nick}!${user}@${host}`);
+  }
+  return [...candidates];
+}
+
+export function resolveIrcAllowlistMatch(params: {
+  allowFrom: string[];
+  message: IrcInboundMessage;
+}): { allowed: boolean; source?: string } {
+  const allowFrom = new Set(
+    params.allowFrom.map((entry) => entry.trim().toLowerCase()).filter(Boolean),
+  );
+  if (allowFrom.has("*")) {
+    return { allowed: true, source: "wildcard" };
+  }
+  const candidates = buildIrcAllowlistCandidates(params.message);
+  for (const candidate of candidates) {
+    if (allowFrom.has(candidate)) {
+      return { allowed: true, source: candidate };
+    }
+  }
+  return { allowed: false };
+}