@actagent/irc 2026.6.2

package/src/setup.test.ts

@@ -0,0 +1,487 @@
+// Irc tests cover setup plugin behavior.
+import {
+  expectStopPendingUntilAbort,
+  startAccountAndTrackLifecycle,
+  waitForStartedMocks,
+} from "actagent/plugin-sdk/channel-test-helpers";
+import {
+  createPluginSetupWizardAdapter,
+  createPluginSetupWizardStatus,
+  createTestWizardPrompter,
+  promptSetupWizardAllowFrom,
+  runSetupWizardConfigure,
+} from "actagent/plugin-sdk/plugin-test-runtime";
+import type { WizardPrompter } from "actagent/plugin-sdk/plugin-test-runtime";
+import { afterAll, afterEach, describe, expect, it, vi } from "vitest";
+import {
+  listIrcAccountIds,
+  resolveDefaultIrcAccountId,
+  type ResolvedIrcAccount,
+} from "./accounts.js";
+import { startIrcGatewayAccount } from "./gateway.js";
+import { clearIrcRuntime, setIrcRuntime } from "./runtime.js";
+import {
+  ircSetupAdapter,
+  parsePort,
+  setIrcAllowFrom,
+  setIrcDmPolicy,
+  setIrcGroupAccess,
+  setIrcNickServ,
+  updateIrcAccountConfig,
+} from "./setup-core.js";
+import { ircSetupWizard } from "./setup-surface.js";
+import type { CoreConfig } from "./types.js";
+
+const hoisted = vi.hoisted(() => ({
+  monitorIrcProvider: vi.fn(),
+  sendMessageIrc: vi.fn(),
+}));
+
+vi.mock("./channel-runtime.js", () => {
+  return {
+    monitorIrcProvider: hoisted.monitorIrcProvider,
+    sendMessageIrc: hoisted.sendMessageIrc,
+  };
+});
+
+afterAll(() => {
+  vi.doUnmock("./channel-runtime.js");
+  vi.resetModules();
+});
+
+const ircSetupPlugin = {
+  id: "irc",
+  meta: {
+    label: "IRC",
+  },
+  config: {
+    defaultAccountId: resolveDefaultIrcAccountId,
+    listAccountIds: listIrcAccountIds,
+  },
+  setupWizard: ircSetupWizard,
+} as never;
+
+const ircConfigureAdapter = createPluginSetupWizardAdapter(ircSetupPlugin);
+const ircStatus = createPluginSetupWizardStatus(ircSetupPlugin);
+
+function buildAccount(): ResolvedIrcAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    name: "default",
+    configured: true,
+    host: "irc.example.com",
+    port: 6697,
+    tls: true,
+    nick: "actagent",
+    username: "actagent",
+    realname: "ACTAgent",
+    password: "",
+    passwordSource: "none",
+    config: {} as ResolvedIrcAccount["config"],
+  };
+}
+
+function installIrcRuntime() {
+  setIrcRuntime({
+    logging: {
+      shouldLogVerbose: vi.fn(() => false),
+      getChildLogger: vi.fn(() => ({
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      })),
+    },
+    channel: {
+      activity: {
+        record: vi.fn(),
+        get: vi.fn(),
+      },
+    },
+  } as never);
+}
+
+describe("irc setup", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+    clearIrcRuntime();
+  });
+
+  it("parses valid ports and falls back for invalid values", () => {
+    expect(parsePort("6697", 6667)).toBe(6697);
+    expect(parsePort(" 7000 ", 6667)).toBe(7000);
+    expect(parsePort("", 6667)).toBe(6667);
+    expect(parsePort("70000", 6667)).toBe(6667);
+    expect(parsePort("abc", 6667)).toBe(6667);
+  });
+
+  it("updates top-level dm policy and allowlist", () => {
+    const cfg: CoreConfig = { channels: { irc: {} } };
+
+    expect(setIrcDmPolicy(cfg, "open")).toStrictEqual({
+      channels: {
+        irc: {
+          dmPolicy: "open",
+          allowFrom: ["*"],
+        },
+      },
+    });
+
+    expect(setIrcAllowFrom(cfg, ["alice", "bob"])).toStrictEqual({
+      channels: {
+        irc: {
+          allowFrom: ["alice", "bob"],
+        },
+      },
+    });
+  });
+
+  it("setup status honors the selected named account", async () => {
+    const status = await ircStatus({
+      cfg: {
+        channels: {
+          irc: {
+            accounts: {
+              ops: {
+                host: "irc.example.com",
+                nick: "ops-bot",
+              },
+              work: {
+                host: "irc.example.com",
+              },
+            },
+          },
+        },
+      } as CoreConfig,
+      accountOverrides: {
+        irc: "work",
+      },
+    });
+
+    expect(status.configured).toBe(false);
+    expect(status.statusLines).toEqual(["IRC: needs host + nick"]);
+  });
+
+  it("setup status honors the configured default account", async () => {
+    const status = await ircStatus({
+      cfg: {
+        channels: {
+          irc: {
+            defaultAccount: "work",
+            accounts: {
+              ops: {
+                host: "irc.example.com",
+                nick: "ops-bot",
+              },
+              work: {
+                host: "irc.example.com",
+                nick: "",
+              },
+            },
+          },
+        },
+      } as CoreConfig,
+      accountOverrides: {},
+    });
+
+    expect(status.configured).toBe(false);
+    expect(status.statusLines).toEqual(["IRC: needs host + nick"]);
+  });
+
+  it("stores nickserv and account config patches on the scoped account", () => {
+    const cfg: CoreConfig = { channels: { irc: {} } };
+
+    expect(
+      setIrcNickServ(cfg, "work", {
+        enabled: true,
+        service: "NickServ",
+      }),
+    ).toStrictEqual({
+      channels: {
+        irc: {
+          accounts: {
+            work: {
+              nickserv: {
+                enabled: true,
+                service: "NickServ",
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(
+      updateIrcAccountConfig(cfg, "work", {
+        host: "irc.libera.chat",
+        nick: "actagent-work",
+      }),
+    ).toStrictEqual({
+      channels: {
+        irc: {
+          accounts: {
+            work: {
+              host: "irc.libera.chat",
+              nick: "actagent-work",
+            },
+          },
+        },
+      },
+    });
+  });
+
+  it("normalizes allowlist groups and handles non-allowlist policies", () => {
+    const cfg: CoreConfig = { channels: { irc: {} } };
+
+    expect(
+      setIrcGroupAccess(
+        cfg,
+        "default",
+        "allowlist",
+        ["actagent", "#ops", "actagent", "*"],
+        (raw) => {
+          const trimmed = raw.trim();
+          if (!trimmed) {
+            return null;
+          }
+          if (trimmed === "*") {
+            return "*";
+          }
+          return trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+        },
+      ),
+    ).toStrictEqual({
+      channels: {
+        irc: {
+          enabled: true,
+          groupPolicy: "allowlist",
+          groups: {
+            "#actagent": {},
+            "#ops": {},
+            "*": {},
+          },
+        },
+      },
+    });
+
+    expect(setIrcGroupAccess(cfg, "default", "disabled", [], () => null)).toStrictEqual({
+      channels: {
+        irc: {
+          enabled: true,
+          groupPolicy: "disabled",
+        },
+      },
+    });
+  });
+
+  it("validates required input and applies normalized account config", () => {
+    const validateInput = ircSetupAdapter.validateInput;
+    const applyAccountConfig = ircSetupAdapter.applyAccountConfig;
+    expect(validateInput).toBeTypeOf("function");
+    expect(applyAccountConfig).toBeTypeOf("function");
+    if (!validateInput) {
+      throw new Error("Expected IRC setup validateInput");
+    }
+
+    expect(
+      validateInput({
+        input: { host: "", nick: "actagent" },
+      } as never),
+    ).toBe("IRC requires host.");
+
+    expect(
+      validateInput({
+        input: { host: "irc.libera.chat", nick: "" },
+      } as never),
+    ).toBe("IRC requires nick.");
+
+    expect(
+      validateInput({
+        input: { host: "irc.libera.chat", nick: "actagent" },
+      } as never),
+    ).toBeNull();
+
+    expect(
+      validateInput({
+        input: { host: "irc.libera.chat", nick: "actagent", port: "+07000" },
+      } as never),
+    ).toBeNull();
+
+    expect(
+      validateInput({
+        input: { host: "irc.libera.chat", nick: "actagent", port: "7000x" },
+      } as never),
+    ).toBe("IRC port must be between 1 and 65535.");
+
+    expect(
+      validateInput({
+        input: { host: "irc.libera.chat", nick: "actagent", port: "70000" },
+      } as never),
+    ).toBe("IRC port must be between 1 and 65535.");
+
+    expect(
+      applyAccountConfig({
+        cfg: { channels: { irc: {} } },
+        accountId: "default",
+        input: {
+          name: "Default",
+          host: " irc.libera.chat ",
+          port: "7000",
+          tls: true,
+          nick: " actagent ",
+          username: " actagent ",
+          realname: " ACTAgent Bot ",
+          password: " secret ",
+          channels: ["#actagent"],
+        },
+      } as never),
+    ).toEqual({
+      channels: {
+        irc: {
+          enabled: true,
+          name: "Default",
+          host: "irc.libera.chat",
+          port: 7000,
+          tls: true,
+          nick: "actagent",
+          username: "actagent",
+          realname: "ACTAgent Bot",
+          password: "secret",
+          channels: ["#actagent"],
+        },
+      },
+    });
+  });
+
+  it("configures host and nick via setup prompts", async () => {
+    const prompter = createTestWizardPrompter({
+      text: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "IRC server host") {
+          return "irc.libera.chat";
+        }
+        if (message === "IRC server port") {
+          return "6697";
+        }
+        if (message === "IRC nick") {
+          return "actagent-bot";
+        }
+        if (message === "IRC username") {
+          return "actagent";
+        }
+        if (message === "IRC real name") {
+          return "ACTAgent Bot";
+        }
+        if (message.startsWith("Auto-join IRC channels")) {
+          return "#actagent, #ops";
+        }
+        if (message.startsWith("IRC channels allowlist")) {
+          return "#actagent, #ops";
+        }
+        throw new Error(`Unexpected prompt: ${message}`);
+      }) as WizardPrompter["text"],
+      confirm: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "Use TLS for IRC?") {
+          return true;
+        }
+        if (message === "Configure IRC channels access?") {
+          return true;
+        }
+        return false;
+      }),
+    });
+
+    const result = await runSetupWizardConfigure({
+      configure: ircConfigureAdapter.configure,
+      cfg: {} as CoreConfig,
+      prompter,
+      options: {},
+    });
+
+    expect(result.accountId).toBe("default");
+    expect(result.cfg.channels?.irc?.enabled).toBe(true);
+    expect(result.cfg.channels?.irc?.host).toBe("irc.libera.chat");
+    expect(result.cfg.channels?.irc?.nick).toBe("actagent-bot");
+    expect(result.cfg.channels?.irc?.tls).toBe(true);
+    expect(result.cfg.channels?.irc?.channels).toEqual(["#actagent", "#ops"]);
+    expect(result.cfg.channels?.irc?.groupPolicy).toBe("allowlist");
+    expect(Object.keys(result.cfg.channels?.irc?.groups ?? {})).toEqual(["#actagent", "#ops"]);
+  });
+
+  it("rejects partial IRC setup wizard ports", async () => {
+    const portPrompt = ircSetupWizard.textInputs?.find((step) => step.inputKey === "httpPort");
+    if (!portPrompt?.validate) {
+      throw new Error("expected IRC port prompt validator");
+    }
+
+    expect(portPrompt.validate({ value: "7000x" } as never)).toBe("Use a port between 1 and 65535");
+    expect(portPrompt.validate({ value: "+07000" } as never)).toBeUndefined();
+    expect(portPrompt.validate({ value: "7000" } as never)).toBeUndefined();
+  });
+
+  it("writes DM allowFrom to top-level config for non-default account prompts", async () => {
+    const prompter = createTestWizardPrompter({
+      text: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "IRC allowFrom (nick or nick!user@host)") {
+          return "Alice, Bob!ident@example.org";
+        }
+        throw new Error(`Unexpected prompt: ${message}`);
+      }) as WizardPrompter["text"],
+      confirm: vi.fn(async () => false),
+    });
+
+    const promptAllowFrom = ircConfigureAdapter.dmPolicy?.promptAllowFrom;
+    if (!promptAllowFrom) {
+      throw new Error("promptAllowFrom unavailable");
+    }
+
+    const cfg: CoreConfig = {
+      channels: {
+        irc: {
+          accounts: {
+            work: {
+              host: "irc.libera.chat",
+              nick: "actagent-work",
+            },
+          },
+        },
+      },
+    };
+
+    const updated = await promptSetupWizardAllowFrom({
+      promptAllowFrom,
+      cfg,
+      prompter,
+      accountId: "work",
+    });
+    if (!updated) {
+      throw new Error("expected IRC allowFrom setup to return updated config");
+    }
+
+    expect(updated.channels?.irc?.allowFrom).toEqual(["alice", "bob!ident@example.org"]);
+    expect(updated.channels?.irc?.accounts?.work?.allowFrom).toBeUndefined();
+  });
+
+  it("keeps startAccount pending until abort, then stops the monitor", async () => {
+    const stop = vi.fn();
+    hoisted.monitorIrcProvider.mockResolvedValue({ stop });
+    installIrcRuntime();
+
+    const { abort, task, isSettled } = startAccountAndTrackLifecycle({
+      startAccount: async (ctx) =>
+        await startIrcGatewayAccount({
+          ...ctx,
+          cfg: ctx.cfg as CoreConfig,
+        }),
+      account: buildAccount(),
+    });
+
+    await expectStopPendingUntilAbort({
+      waitForStarted: waitForStartedMocks(hoisted.monitorIrcProvider),
+      isSettled,
+      abort,
+      task,
+      stop,
+    });
+  });
+});

package/src/types.ts

@@ -0,0 +1,101 @@
+// Irc type declarations define plugin contracts.
+import type {
+  BlockStreamingCoalesceConfig,
+  DmConfig,
+  DmPolicy,
+  GroupPolicy,
+  GroupToolPolicyBySenderConfig,
+  GroupToolPolicyConfig,
+  MarkdownConfig,
+  ACTAgentConfig,
+  BaseProbeResult,
+} from "./runtime-api.js";
+
+export type IrcChannelConfig = {
+  requireMention?: boolean;
+  tools?: GroupToolPolicyConfig;
+  toolsBySender?: GroupToolPolicyBySenderConfig;
+  skills?: string[];
+  enabled?: boolean;
+  allowFrom?: Array<string | number>;
+  systemPrompt?: string;
+};
+
+export type IrcNickServConfig = {
+  enabled?: boolean;
+  service?: string;
+  password?: string;
+  passwordFile?: string;
+  register?: boolean;
+  registerEmail?: string;
+};
+
+export type IrcAccountConfig = {
+  name?: string;
+  enabled?: boolean;
+  /**
+   * Break-glass override: allow nick-only allowlist matching.
+   * Default behavior requires host/user-qualified identities.
+   */
+  dangerouslyAllowNameMatching?: boolean;
+  host?: string;
+  port?: number;
+  tls?: boolean;
+  nick?: string;
+  username?: string;
+  realname?: string;
+  password?: string;
+  passwordFile?: string;
+  nickserv?: IrcNickServConfig;
+  dmPolicy?: DmPolicy;
+  allowFrom?: Array<string | number>;
+  defaultTo?: string;
+  groupPolicy?: GroupPolicy;
+  groupAllowFrom?: Array<string | number>;
+  groups?: Record<string, IrcChannelConfig>;
+  channels?: string[];
+  mentionPatterns?: string[];
+  markdown?: MarkdownConfig;
+  historyLimit?: number;
+  dmHistoryLimit?: number;
+  dms?: Record<string, DmConfig>;
+  textChunkLimit?: number;
+  chunkMode?: "length" | "newline";
+  blockStreaming?: boolean;
+  blockStreamingCoalesce?: BlockStreamingCoalesceConfig;
+  responsePrefix?: string;
+  mediaMaxMb?: number;
+};
+
+type IrcConfig = IrcAccountConfig & {
+  accounts?: Record<string, IrcAccountConfig>;
+  defaultAccount?: string;
+};
+
+export type CoreConfig = ACTAgentConfig & {
+  channels?: ACTAgentConfig["channels"] & {
+    irc?: IrcConfig;
+  };
+};
+
+export type IrcInboundMessage = {
+  messageId: string;
+  /** Conversation peer id: channel name for groups, sender nick for DMs. */
+  target: string;
+  /** Raw IRC PRIVMSG target (bot nick for DMs, channel for groups). */
+  rawTarget?: string;
+  senderNick: string;
+  senderUser?: string;
+  senderHost?: string;
+  text: string;
+  timestamp: number;
+  isGroup: boolean;
+};
+
+export type IrcProbe = BaseProbeResult<string> & {
+  host: string;
+  port: number;
+  tls: boolean;
+  nick: string;
+  latencyMs?: number;
+};

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}