@poolzin/pool-bot 2026.2.17 → 2026.2.19

package/extensions/irc/src/onboarding.ts

@@ -0,0 +1,479 @@
+import {
+  addWildcardAllowFrom,
+  DEFAULT_ACCOUNT_ID,
+  formatDocsLink,
+  promptAccountId,
+  promptChannelAccessConfig,
+  type ChannelOnboardingAdapter,
+  type ChannelOnboardingDmPolicy,
+  type DmPolicy,
+  type WizardPrompter,
+} from "poolbot/plugin-sdk";
+import { listIrcAccountIds, resolveDefaultIrcAccountId, resolveIrcAccount } from "./accounts.js";
+import {
+  isChannelTarget,
+  normalizeIrcAllowEntry,
+  normalizeIrcMessagingTarget,
+} from "./normalize.js";
+import type { CoreConfig, IrcAccountConfig, IrcNickServConfig } from "./types.js";
+
+const channel = "irc" as const;
+
+function parseListInput(raw: string): string[] {
+  return raw
+    .split(/[\n,;]+/g)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function parsePort(raw: string, fallback: number): number {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isFinite(parsed) || parsed < 1 || parsed > 65535) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function normalizeGroupEntry(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (trimmed === "*") {
+    return "*";
+  }
+  const normalized = normalizeIrcMessagingTarget(trimmed) ?? trimmed;
+  if (isChannelTarget(normalized)) {
+    return normalized;
+  }
+  return `#${normalized.replace(/^#+/, "")}`;
+}
+
+function updateIrcAccountConfig(
+  cfg: CoreConfig,
+  accountId: string,
+  patch: Partial<IrcAccountConfig>,
+): CoreConfig {
+  const current = cfg.channels?.irc ?? {};
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        irc: {
+          ...current,
+          ...patch,
+        },
+      },
+    };
+  }
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      irc: {
+        ...current,
+        accounts: {
+          ...current.accounts,
+          [accountId]: {
+            ...current.accounts?.[accountId],
+            ...patch,
+          },
+        },
+      },
+    },
+  };
+}
+
+function setIrcDmPolicy(cfg: CoreConfig, dmPolicy: DmPolicy): CoreConfig {
+  const allowFrom =
+    dmPolicy === "open" ? addWildcardAllowFrom(cfg.channels?.irc?.allowFrom) : undefined;
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      irc: {
+        ...cfg.channels?.irc,
+        dmPolicy,
+        ...(allowFrom ? { allowFrom } : {}),
+      },
+    },
+  };
+}
+
+function setIrcAllowFrom(cfg: CoreConfig, allowFrom: string[]): CoreConfig {
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      irc: {
+        ...cfg.channels?.irc,
+        allowFrom,
+      },
+    },
+  };
+}
+
+function setIrcNickServ(
+  cfg: CoreConfig,
+  accountId: string,
+  nickserv?: IrcNickServConfig,
+): CoreConfig {
+  return updateIrcAccountConfig(cfg, accountId, { nickserv });
+}
+
+function setIrcGroupAccess(
+  cfg: CoreConfig,
+  accountId: string,
+  policy: "open" | "allowlist" | "disabled",
+  entries: string[],
+): CoreConfig {
+  if (policy !== "allowlist") {
+    return updateIrcAccountConfig(cfg, accountId, { enabled: true, groupPolicy: policy });
+  }
+  const normalizedEntries = [
+    ...new Set(entries.map((entry) => normalizeGroupEntry(entry)).filter(Boolean)),
+  ];
+  const groups = Object.fromEntries(normalizedEntries.map((entry) => [entry, {}]));
+  return updateIrcAccountConfig(cfg, accountId, {
+    enabled: true,
+    groupPolicy: "allowlist",
+    groups,
+  });
+}
+
+async function noteIrcSetupHelp(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "IRC needs server host + bot nick.",
+      "Recommended: TLS on port 6697.",
+      "Optional: NickServ identify/register can be configured in onboarding.",
+      'Set channels.irc.groupPolicy="allowlist" and channels.irc.groups for tighter channel control.',
+      'Note: IRC channels are mention-gated by default. To allow unmentioned replies, set channels.irc.groups["#channel"].requireMention=false (or "*" for all).',
+      "Env vars supported: IRC_HOST, IRC_PORT, IRC_TLS, IRC_NICK, IRC_USERNAME, IRC_REALNAME, IRC_PASSWORD, IRC_CHANNELS, IRC_NICKSERV_PASSWORD, IRC_NICKSERV_REGISTER_EMAIL.",
+      `Docs: ${formatDocsLink("/channels/irc", "channels/irc")}`,
+    ].join("\n"),
+    "IRC setup",
+  );
+}
+
+async function promptIrcAllowFrom(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+  accountId?: string;
+}): Promise<CoreConfig> {
+  const existing = params.cfg.channels?.irc?.allowFrom ?? [];
+
+  await params.prompter.note(
+    [
+      "Allowlist IRC DMs by sender.",
+      "Examples:",
+      "- alice",
+      "- alice!ident@example.org",
+      "Multiple entries: comma-separated.",
+    ].join("\n"),
+    "IRC allowlist",
+  );
+
+  const raw = await params.prompter.text({
+    message: "IRC allowFrom (nick or nick!user@host)",
+    placeholder: "alice, bob!ident@example.org",
+    initialValue: existing[0] ? String(existing[0]) : undefined,
+    validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+  });
+
+  const parsed = parseListInput(String(raw));
+  const normalized = [
+    ...new Set(
+      parsed
+        .map((entry) => normalizeIrcAllowEntry(entry))
+        .map((entry) => entry.trim())
+        .filter(Boolean),
+    ),
+  ];
+  return setIrcAllowFrom(params.cfg, normalized);
+}
+
+async function promptIrcNickServConfig(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+  accountId: string;
+}): Promise<CoreConfig> {
+  const resolved = resolveIrcAccount({ cfg: params.cfg, accountId: params.accountId });
+  const existing = resolved.config.nickserv;
+  const hasExisting = Boolean(existing?.password || existing?.passwordFile);
+  const wants = await params.prompter.confirm({
+    message: hasExisting ? "Update NickServ settings?" : "Configure NickServ identify/register?",
+    initialValue: hasExisting,
+  });
+  if (!wants) {
+    return params.cfg;
+  }
+
+  const service = String(
+    await params.prompter.text({
+      message: "NickServ service nick",
+      initialValue: existing?.service || "NickServ",
+      validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+    }),
+  ).trim();
+
+  const useEnvPassword =
+    params.accountId === DEFAULT_ACCOUNT_ID &&
+    Boolean(process.env.IRC_NICKSERV_PASSWORD?.trim()) &&
+    !(existing?.password || existing?.passwordFile)
+      ? await params.prompter.confirm({
+          message: "IRC_NICKSERV_PASSWORD detected. Use env var?",
+          initialValue: true,
+        })
+      : false;
+
+  const password = useEnvPassword
+    ? undefined
+    : String(
+        await params.prompter.text({
+          message: "NickServ password (blank to disable NickServ auth)",
+          validate: () => undefined,
+        }),
+      ).trim();
+
+  if (!password && !useEnvPassword) {
+    return setIrcNickServ(params.cfg, params.accountId, {
+      enabled: false,
+      service,
+    });
+  }
+
+  const register = await params.prompter.confirm({
+    message: "Send NickServ REGISTER on connect?",
+    initialValue: existing?.register ?? false,
+  });
+  const registerEmail = register
+    ? String(
+        await params.prompter.text({
+          message: "NickServ register email",
+          initialValue:
+            existing?.registerEmail ||
+            (params.accountId === DEFAULT_ACCOUNT_ID
+              ? process.env.IRC_NICKSERV_REGISTER_EMAIL
+              : undefined),
+          validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+        }),
+      ).trim()
+    : undefined;
+
+  return setIrcNickServ(params.cfg, params.accountId, {
+    enabled: true,
+    service,
+    ...(password ? { password } : {}),
+    register,
+    ...(registerEmail ? { registerEmail } : {}),
+  });
+}
+
+const dmPolicy: ChannelOnboardingDmPolicy = {
+  label: "IRC",
+  channel,
+  policyKey: "channels.irc.dmPolicy",
+  allowFromKey: "channels.irc.allowFrom",
+  getCurrent: (cfg) => (cfg as CoreConfig).channels?.irc?.dmPolicy ?? "pairing",
+  setPolicy: (cfg, policy) => setIrcDmPolicy(cfg as CoreConfig, policy),
+  promptAllowFrom: promptIrcAllowFrom,
+};
+
+export const ircOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const coreCfg = cfg as CoreConfig;
+    const configured = listIrcAccountIds(coreCfg).some(
+      (accountId) => resolveIrcAccount({ cfg: coreCfg, accountId }).configured,
+    );
+    return {
+      channel,
+      configured,
+      statusLines: [`IRC: ${configured ? "configured" : "needs host + nick"}`],
+      selectionHint: configured ? "configured" : "needs host + nick",
+      quickstartScore: configured ? 1 : 0,
+    };
+  },
+  configure: async ({
+    cfg,
+    prompter,
+    accountOverrides,
+    shouldPromptAccountIds,
+    forceAllowFrom,
+  }) => {
+    let next = cfg as CoreConfig;
+    const ircOverride = accountOverrides.irc?.trim();
+    const defaultAccountId = resolveDefaultIrcAccountId(next);
+    let accountId = ircOverride || defaultAccountId;
+    if (shouldPromptAccountIds && !ircOverride) {
+      accountId = await promptAccountId({
+        cfg: next,
+        prompter,
+        label: "IRC",
+        currentId: accountId,
+        listAccountIds: listIrcAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    const resolved = resolveIrcAccount({ cfg: next, accountId });
+    const isDefaultAccount = accountId === DEFAULT_ACCOUNT_ID;
+    const envHost = isDefaultAccount ? process.env.IRC_HOST?.trim() : "";
+    const envNick = isDefaultAccount ? process.env.IRC_NICK?.trim() : "";
+    const envReady = Boolean(envHost && envNick);
+
+    if (!resolved.configured) {
+      await noteIrcSetupHelp(prompter);
+    }
+
+    let useEnv = false;
+    if (envReady && isDefaultAccount && !resolved.config.host && !resolved.config.nick) {
+      useEnv = await prompter.confirm({
+        message: "IRC_HOST and IRC_NICK detected. Use env vars?",
+        initialValue: true,
+      });
+    }
+
+    if (useEnv) {
+      next = updateIrcAccountConfig(next, accountId, { enabled: true });
+    } else {
+      const host = String(
+        await prompter.text({
+          message: "IRC server host",
+          initialValue: resolved.config.host || envHost || undefined,
+          validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+        }),
+      ).trim();
+
+      const tls = await prompter.confirm({
+        message: "Use TLS for IRC?",
+        initialValue: resolved.config.tls ?? true,
+      });
+      const defaultPort = resolved.config.port ?? (tls ? 6697 : 6667);
+      const portInput = await prompter.text({
+        message: "IRC server port",
+        initialValue: String(defaultPort),
+        validate: (value) => {
+          const parsed = Number.parseInt(String(value ?? "").trim(), 10);
+          return Number.isFinite(parsed) && parsed >= 1 && parsed <= 65535
+            ? undefined
+            : "Use a port between 1 and 65535";
+        },
+      });
+      const port = parsePort(String(portInput), defaultPort);
+
+      const nick = String(
+        await prompter.text({
+          message: "IRC nick",
+          initialValue: resolved.config.nick || envNick || undefined,
+          validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+        }),
+      ).trim();
+
+      const username = String(
+        await prompter.text({
+          message: "IRC username",
+          initialValue: resolved.config.username || nick || "poolbot",
+          validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+        }),
+      ).trim();
+
+      const realname = String(
+        await prompter.text({
+          message: "IRC real name",
+          initialValue: resolved.config.realname || "OpenClaw",
+          validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+        }),
+      ).trim();
+
+      const channelsRaw = await prompter.text({
+        message: "Auto-join IRC channels (optional, comma-separated)",
+        placeholder: "#openclaw, #ops",
+        initialValue: (resolved.config.channels ?? []).join(", "),
+      });
+      const channels = [
+        ...new Set(
+          parseListInput(String(channelsRaw))
+            .map((entry) => normalizeGroupEntry(entry))
+            .filter((entry): entry is string => Boolean(entry && entry !== "*"))
+            .filter((entry) => isChannelTarget(entry)),
+        ),
+      ];
+
+      next = updateIrcAccountConfig(next, accountId, {
+        enabled: true,
+        host,
+        port,
+        tls,
+        nick,
+        username,
+        realname,
+        channels: channels.length > 0 ? channels : undefined,
+      });
+    }
+
+    const afterConfig = resolveIrcAccount({ cfg: next, accountId });
+    const accessConfig = await promptChannelAccessConfig({
+      prompter,
+      label: "IRC channels",
+      currentPolicy: afterConfig.config.groupPolicy ?? "allowlist",
+      currentEntries: Object.keys(afterConfig.config.groups ?? {}),
+      placeholder: "#openclaw, #ops, *",
+      updatePrompt: Boolean(afterConfig.config.groups),
+    });
+    if (accessConfig) {
+      next = setIrcGroupAccess(next, accountId, accessConfig.policy, accessConfig.entries);
+
+      // Mention gating: groups/channels are mention-gated by default. Make this explicit in onboarding.
+      const wantsMentions = await prompter.confirm({
+        message: "Require @mention to reply in IRC channels?",
+        initialValue: true,
+      });
+      if (!wantsMentions) {
+        const resolvedAfter = resolveIrcAccount({ cfg: next, accountId });
+        const groups = resolvedAfter.config.groups ?? {};
+        const patched = Object.fromEntries(
+          Object.entries(groups).map(([key, value]) => [key, { ...value, requireMention: false }]),
+        );
+        next = updateIrcAccountConfig(next, accountId, { groups: patched });
+      }
+    }
+
+    if (forceAllowFrom) {
+      next = await promptIrcAllowFrom({ cfg: next, prompter, accountId });
+    }
+    next = await promptIrcNickServConfig({
+      cfg: next,
+      prompter,
+      accountId,
+    });
+
+    await prompter.note(
+      [
+        "Next: restart gateway and verify status.",
+        "Command: openclaw channels status --probe",
+        `Docs: ${formatDocsLink("/channels/irc", "channels/irc")}`,
+      ].join("\n"),
+      "IRC next steps",
+    );
+
+    return { cfg: next, accountId };
+  },
+  dmPolicy,
+  disable: (cfg) => ({
+    ...(cfg as CoreConfig),
+    channels: {
+      ...(cfg as CoreConfig).channels,
+      irc: {
+        ...(cfg as CoreConfig).channels?.irc,
+        enabled: false,
+      },
+    },
+  }),
+};

package/extensions/irc/src/policy.ts

@@ -0,0 +1,157 @@
+import { normalizeIrcAllowlist, resolveIrcAllowlistMatch } from "./normalize.js";
+import type { IrcAccountConfig, IrcChannelConfig } from "./types.js";
+import type { IrcInboundMessage } from "./types.js";
+
+export type IrcGroupMatch = {
+  allowed: boolean;
+  groupConfig?: IrcChannelConfig;
+  wildcardConfig?: IrcChannelConfig;
+  hasConfiguredGroups: boolean;
+};
+
+export type IrcGroupAccessGate = {
+  allowed: boolean;
+  reason: string;
+};
+
+export function resolveIrcGroupMatch(params: {
+  groups?: Record<string, IrcChannelConfig>;
+  target: string;
+}): IrcGroupMatch {
+  const groups = params.groups ?? {};
+  const hasConfiguredGroups = Object.keys(groups).length > 0;
+
+  // IRC channel targets are case-insensitive, but config keys are plain strings.
+  // To avoid surprising drops (e.g. "#TUIRC-DEV" vs "#tuirc-dev"), match
+  // group config keys case-insensitively.
+  const direct = groups[params.target];
+  if (direct) {
+    return {
+      // "allowed" means the target matched an allowlisted key.
+      // Explicit disables are handled later by resolveIrcGroupAccessGate.
+      allowed: true,
+      groupConfig: direct,
+      wildcardConfig: groups["*"],
+      hasConfiguredGroups,
+    };
+  }
+
+  const targetLower = params.target.toLowerCase();
+  const directKey = Object.keys(groups).find((key) => key.toLowerCase() === targetLower);
+  if (directKey) {
+    const matched = groups[directKey];
+    if (matched) {
+      return {
+        // "allowed" means the target matched an allowlisted key.
+        // Explicit disables are handled later by resolveIrcGroupAccessGate.
+        allowed: true,
+        groupConfig: matched,
+        wildcardConfig: groups["*"],
+        hasConfiguredGroups,
+      };
+    }
+  }
+
+  const wildcard = groups["*"];
+  if (wildcard) {
+    return {
+      // "allowed" means the target matched an allowlisted key.
+      // Explicit disables are handled later by resolveIrcGroupAccessGate.
+      allowed: true,
+      wildcardConfig: wildcard,
+      hasConfiguredGroups,
+    };
+  }
+  return {
+    allowed: false,
+    hasConfiguredGroups,
+  };
+}
+
+export function resolveIrcGroupAccessGate(params: {
+  groupPolicy: IrcAccountConfig["groupPolicy"];
+  groupMatch: IrcGroupMatch;
+}): IrcGroupAccessGate {
+  const policy = params.groupPolicy ?? "allowlist";
+  if (policy === "disabled") {
+    return { allowed: false, reason: "groupPolicy=disabled" };
+  }
+
+  // In open mode, unconfigured channels are allowed (mention-gated) but explicit
+  // per-channel/wildcard disables still apply.
+  if (policy === "allowlist") {
+    if (!params.groupMatch.hasConfiguredGroups) {
+      return {
+        allowed: false,
+        reason: "groupPolicy=allowlist and no groups configured",
+      };
+    }
+    if (!params.groupMatch.allowed) {
+      return { allowed: false, reason: "not allowlisted" };
+    }
+  }
+
+  if (
+    params.groupMatch.groupConfig?.enabled === false ||
+    params.groupMatch.wildcardConfig?.enabled === false
+  ) {
+    return { allowed: false, reason: "disabled" };
+  }
+
+  return { allowed: true, reason: policy === "open" ? "open" : "allowlisted" };
+}
+
+export function resolveIrcRequireMention(params: {
+  groupConfig?: IrcChannelConfig;
+  wildcardConfig?: IrcChannelConfig;
+}): boolean {
+  if (params.groupConfig?.requireMention !== undefined) {
+    return params.groupConfig.requireMention;
+  }
+  if (params.wildcardConfig?.requireMention !== undefined) {
+    return params.wildcardConfig.requireMention;
+  }
+  return true;
+}
+
+export function resolveIrcMentionGate(params: {
+  isGroup: boolean;
+  requireMention: boolean;
+  wasMentioned: boolean;
+  hasControlCommand: boolean;
+  allowTextCommands: boolean;
+  commandAuthorized: boolean;
+}): { shouldSkip: boolean; reason: string } {
+  if (!params.isGroup) {
+    return { shouldSkip: false, reason: "direct" };
+  }
+  if (!params.requireMention) {
+    return { shouldSkip: false, reason: "mention-not-required" };
+  }
+  if (params.wasMentioned) {
+    return { shouldSkip: false, reason: "mentioned" };
+  }
+  if (params.hasControlCommand && params.allowTextCommands && params.commandAuthorized) {
+    return { shouldSkip: false, reason: "authorized-command" };
+  }
+  return { shouldSkip: true, reason: "missing-mention" };
+}
+
+export function resolveIrcGroupSenderAllowed(params: {
+  groupPolicy: IrcAccountConfig["groupPolicy"];
+  message: IrcInboundMessage;
+  outerAllowFrom: string[];
+  innerAllowFrom: string[];
+}): boolean {
+  const policy = params.groupPolicy ?? "allowlist";
+  const inner = normalizeIrcAllowlist(params.innerAllowFrom);
+  const outer = normalizeIrcAllowlist(params.outerAllowFrom);
+
+  if (inner.length > 0) {
+    return resolveIrcAllowlistMatch({ allowFrom: inner, message: params.message }).allowed;
+  }
+  if (outer.length > 0) {
+    return resolveIrcAllowlistMatch({ allowFrom: outer, message: params.message }).allowed;
+  }
+  return policy === "open";
+}

package/extensions/irc/src/probe.ts

@@ -0,0 +1,53 @@
+import { resolveIrcAccount } from "./accounts.js";
+import { connectIrcClient } from "./client.js";
+import { buildIrcConnectOptions } from "./connect-options.js";
+import type { CoreConfig, IrcProbe } from "./types.js";
+
+function formatError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return typeof err === "string" ? err : JSON.stringify(err);
+}
+
+export async function probeIrc(
+  cfg: CoreConfig,
+  opts?: { accountId?: string; timeoutMs?: number },
+): Promise<IrcProbe> {
+  const account = resolveIrcAccount({ cfg, accountId: opts?.accountId });
+  const base: IrcProbe = {
+    ok: false,
+    host: account.host,
+    port: account.port,
+    tls: account.tls,
+    nick: account.nick,
+  };
+
+  if (!account.configured) {
+    return {
+      ...base,
+      error: "missing host or nick",
+    };
+  }
+
+  const started = Date.now();
+  try {
+    const client = await connectIrcClient(
+      buildIrcConnectOptions(account, {
+        connectTimeoutMs: opts?.timeoutMs ?? 8000,
+      }),
+    );
+    const elapsed = Date.now() - started;
+    client.quit("probe");
+    return {
+      ...base,
+      ok: true,
+      latencyMs: elapsed,
+    };
+  } catch (err) {
+    return {
+      ...base,
+      error: formatError(err),
+    };
+  }
+}