@actagent/irc 2026.6.2

package/src/connect-options.test.ts

@@ -0,0 +1,48 @@
+// Irc tests cover connect options plugin behavior.
+import { describe, expect, it } from "vitest";
+import { buildIrcConnectOptions } from "./connect-options.js";
+
+describe("buildIrcConnectOptions", () => {
+  it("copies resolved account connection fields and NickServ config", () => {
+    const account = {
+      host: "irc.libera.chat",
+      port: 6697,
+      tls: true,
+      nick: "actagent",
+      username: "actagent",
+      realname: "ACTAgent Bot",
+      password: "server-pass",
+      config: {
+        nickserv: {
+          enabled: true,
+          service: "NickServ",
+          password: "nickserv-pass",
+          register: true,
+          registerEmail: "bot@example.com",
+        },
+      },
+    };
+
+    expect(
+      buildIrcConnectOptions(account as never, {
+        connectTimeoutMs: 1234,
+      }),
+    ).toEqual({
+      host: "irc.libera.chat",
+      port: 6697,
+      tls: true,
+      nick: "actagent",
+      username: "actagent",
+      realname: "ACTAgent Bot",
+      password: "server-pass",
+      nickserv: {
+        enabled: true,
+        service: "NickServ",
+        password: "nickserv-pass",
+        register: true,
+        registerEmail: "bot@example.com",
+      },
+      connectTimeoutMs: 1234,
+    });
+  });
+});

package/src/connect-options.ts

@@ -0,0 +1,31 @@
+// Irc plugin module implements connect options behavior.
+import type { ResolvedIrcAccount } from "./accounts.js";
+import type { IrcClientOptions } from "./client.js";
+
+type IrcConnectOverrides = Omit<
+  Partial<IrcClientOptions>,
+  "host" | "port" | "tls" | "nick" | "username" | "realname" | "password" | "nickserv"
+>;
+
+export function buildIrcConnectOptions(
+  account: ResolvedIrcAccount,
+  overrides: IrcConnectOverrides = {},
+): IrcClientOptions {
+  return {
+    host: account.host,
+    port: account.port,
+    tls: account.tls,
+    nick: account.nick,
+    username: account.username,
+    realname: account.realname,
+    password: account.password,
+    nickserv: {
+      enabled: account.config.nickserv?.enabled,
+      service: account.config.nickserv?.service,
+      password: account.config.nickserv?.password,
+      register: account.config.nickserv?.register,
+      registerEmail: account.config.nickserv?.registerEmail,
+    },
+    ...overrides,
+  };
+}

package/src/control-chars.test.ts

@@ -0,0 +1,18 @@
+// Irc tests cover control chars plugin behavior.
+import { describe, expect, it } from "vitest";
+import { hasIrcControlChars, isIrcControlChar, stripIrcControlChars } from "./control-chars.js";
+
+describe("irc control char helpers", () => {
+  it("detects IRC control characters by codepoint", () => {
+    expect(isIrcControlChar(0x00)).toBe(true);
+    expect(isIrcControlChar(0x1f)).toBe(true);
+    expect(isIrcControlChar(0x7f)).toBe(true);
+    expect(isIrcControlChar(0x20)).toBe(false);
+  });
+
+  it("detects and strips IRC control characters from strings", () => {
+    expect(hasIrcControlChars("hello\u0002world")).toBe(true);
+    expect(hasIrcControlChars("hello world")).toBe(false);
+    expect(stripIrcControlChars("he\u0002llo\u007f world")).toBe("hello world");
+  });
+});

package/src/control-chars.ts

@@ -0,0 +1,23 @@
+// Irc plugin module implements control chars behavior.
+export function isIrcControlChar(charCode: number): boolean {
+  return charCode <= 0x1f || charCode === 0x7f;
+}
+
+export function hasIrcControlChars(value: string): boolean {
+  for (const char of value) {
+    if (isIrcControlChar(char.charCodeAt(0))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function stripIrcControlChars(value: string): string {
+  let out = "";
+  for (const char of value) {
+    if (!isIrcControlChar(char.charCodeAt(0))) {
+      out += char;
+    }
+  }
+  return out;
+}

package/src/doctor.ts

@@ -0,0 +1,55 @@
+// Irc plugin module implements doctor behavior.
+import { createDangerousNameMatchingMutableAllowlistWarningCollector } from "actagent/plugin-sdk/channel-policy";
+import { normalizeLowercaseStringOrEmpty } from "actagent/plugin-sdk/string-coerce-runtime";
+
+function asObjectRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function isIrcMutableAllowEntry(raw: string): boolean {
+  const text = normalizeLowercaseStringOrEmpty(raw);
+  if (!text || text === "*") {
+    return false;
+  }
+
+  const normalized = text
+    .replace(/^irc:/, "")
+    .replace(/^user:/, "")
+    .trim();
+
+  return !normalized.includes("!") && !normalized.includes("@");
+}
+
+export const collectIrcMutableAllowlistWarnings =
+  createDangerousNameMatchingMutableAllowlistWarningCollector({
+    channel: "irc",
+    detector: isIrcMutableAllowEntry,
+    collectLists: (scope) => {
+      const lists = [
+        {
+          pathLabel: `${scope.prefix}.allowFrom`,
+          list: scope.account.allowFrom,
+        },
+        {
+          pathLabel: `${scope.prefix}.groupAllowFrom`,
+          list: scope.account.groupAllowFrom,
+        },
+      ];
+      const groups = asObjectRecord(scope.account.groups);
+      if (groups) {
+        for (const [groupKey, groupRaw] of Object.entries(groups)) {
+          const group = asObjectRecord(groupRaw);
+          if (!group) {
+            continue;
+          }
+          lists.push({
+            pathLabel: `${scope.prefix}.groups.${groupKey}.allowFrom`,
+            list: group.allowFrom,
+          });
+        }
+      }
+      return lists;
+    },
+  });

package/src/gateway.ts

@@ -0,0 +1,54 @@
+// Irc plugin module implements gateway behavior.
+import { runStoppablePassiveMonitor } from "actagent/plugin-sdk/extension-shared";
+import type { ChannelAccountSnapshot } from "actagent/plugin-sdk/status-helpers";
+import type { ResolvedIrcAccount } from "./accounts.js";
+import { createAccountStatusSink } from "./channel-api.js";
+import type { RuntimeEnv } from "./runtime-api.js";
+import type { CoreConfig } from "./types.js";
+
+type IrcChannelRuntimeModule = typeof import("./channel-runtime.js");
+
+let ircChannelRuntimePromise: Promise<IrcChannelRuntimeModule> | undefined;
+
+async function loadIrcChannelRuntime(): Promise<IrcChannelRuntimeModule> {
+  ircChannelRuntimePromise ??= import("./channel-runtime.js");
+  return await ircChannelRuntimePromise;
+}
+
+export async function startIrcGatewayAccount(ctx: {
+  cfg: CoreConfig;
+  accountId: string;
+  account: ResolvedIrcAccount;
+  runtime: RuntimeEnv;
+  abortSignal: AbortSignal;
+  setStatus: (next: ChannelAccountSnapshot) => void;
+  log?: {
+    info?: (message: string) => void;
+  };
+}): Promise<void> {
+  const account = ctx.account;
+  const statusSink = createAccountStatusSink({
+    accountId: ctx.accountId,
+    setStatus: ctx.setStatus,
+  });
+  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();
+  await runStoppablePassiveMonitor({
+    abortSignal: ctx.abortSignal,
+    start: async () =>
+      await monitorIrcProvider({
+        accountId: account.accountId,
+        config: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        statusSink,
+      }),
+  });
+}

package/src/inbound.behavior.test.ts

@@ -0,0 +1,247 @@
+// Irc tests cover inbound.behavior plugin behavior.
+import { createPluginRuntimeMock } from "actagent/plugin-sdk/channel-test-helpers";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedIrcAccount } from "./accounts.js";
+import { handleIrcInbound } from "./inbound.js";
+import type { RuntimeEnv } from "./runtime-api.js";
+import { clearIrcRuntime, setIrcRuntime } from "./runtime.js";
+import type { CoreConfig, IrcInboundMessage } from "./types.js";
+
+const {
+  buildMentionRegexesMock,
+  hasControlCommandMock,
+  matchesMentionPatternsMock,
+  readAllowFromStoreMock,
+  shouldHandleTextCommandsMock,
+  upsertPairingRequestMock,
+} = vi.hoisted(() => {
+  return {
+    buildMentionRegexesMock: vi.fn(() => []),
+    hasControlCommandMock: vi.fn(() => false),
+    matchesMentionPatternsMock: vi.fn(() => false),
+    readAllowFromStoreMock: vi.fn(async () => []),
+    shouldHandleTextCommandsMock: vi.fn(() => false),
+    upsertPairingRequestMock: vi.fn(async () => ({ code: "CODE", created: true })),
+  };
+});
+
+function installIrcRuntime() {
+  setIrcRuntime({
+    channel: {
+      pairing: {
+        readAllowFromStore: readAllowFromStoreMock,
+        upsertPairingRequest: upsertPairingRequestMock,
+      },
+      commands: {
+        shouldHandleTextCommands: shouldHandleTextCommandsMock,
+      },
+      text: {
+        hasControlCommand: hasControlCommandMock,
+      },
+      mentions: {
+        buildMentionRegexes: buildMentionRegexesMock,
+        matchesMentionPatterns: matchesMentionPatternsMock,
+      },
+    },
+  } as never);
+}
+
+function createRuntimeEnv() {
+  return {
+    log: vi.fn(),
+    error: vi.fn(),
+  } as unknown as RuntimeEnv;
+}
+
+function createAccount(overrides?: Partial<ResolvedIrcAccount>): ResolvedIrcAccount {
+  return {
+    accountId: "default",
+    enabled: true,
+    server: "irc.example.com",
+    nick: "ACTAgent",
+    config: {
+      dmPolicy: "pairing",
+      allowFrom: [],
+      groupPolicy: "allowlist",
+      groupAllowFrom: [],
+    },
+    ...overrides,
+  } as ResolvedIrcAccount;
+}
+
+function createMessage(overrides?: Partial<IrcInboundMessage>): IrcInboundMessage {
+  return {
+    messageId: "msg-1",
+    target: "alice",
+    senderNick: "alice",
+    senderUser: "ident",
+    senderHost: "example.com",
+    text: "hello",
+    timestamp: Date.now(),
+    isGroup: false,
+    ...overrides,
+  };
+}
+
+function resetInboundMocks() {
+  buildMentionRegexesMock.mockReset().mockReturnValue([]);
+  hasControlCommandMock.mockReset().mockReturnValue(false);
+  matchesMentionPatternsMock.mockReset().mockReturnValue(false);
+  readAllowFromStoreMock.mockReset().mockResolvedValue([]);
+  shouldHandleTextCommandsMock.mockReset().mockReturnValue(false);
+  upsertPairingRequestMock.mockReset().mockResolvedValue({ code: "CODE", created: true });
+}
+
+describe("irc inbound behavior", () => {
+  beforeEach(() => {
+    resetInboundMocks();
+    installIrcRuntime();
+  });
+
+  afterEach(() => {
+    clearIrcRuntime();
+  });
+
+  it("issues a DM pairing challenge and sends the reply to the sender nick", async () => {
+    const sendReply = vi.fn<(target: string, text: string, replyToId?: string) => Promise<void>>(
+      async () => {},
+    );
+
+    await handleIrcInbound({
+      message: createMessage(),
+      account: createAccount(),
+      config: { channels: { irc: {} } } as CoreConfig,
+      runtime: createRuntimeEnv(),
+      sendReply,
+    });
+
+    expect(upsertPairingRequestMock).toHaveBeenCalledWith({
+      channel: "irc",
+      accountId: "default",
+      id: "alice!ident@example.com",
+      meta: { name: "alice" },
+    });
+    expect(sendReply).toHaveBeenCalledTimes(1);
+    expect(sendReply).toHaveBeenCalledWith(
+      "alice",
+      [
+        "ACTAgent: access not configured.",
+        "",
+        "Your IRC id: alice!ident@example.com",
+        "Pairing code:",
+        "```",
+        "CODE",
+        "```",
+        "",
+        "Ask the bot owner to approve with:",
+        "```",
+        "actagent pairing approve irc CODE",
+        "```",
+      ].join("\n"),
+      undefined,
+    );
+  });
+
+  it("drops unauthorized group control commands before dispatch", async () => {
+    const runtime = createRuntimeEnv();
+    shouldHandleTextCommandsMock.mockReturnValue(true);
+    hasControlCommandMock.mockReturnValue(true);
+
+    await handleIrcInbound({
+      message: createMessage({
+        target: "#ops",
+        isGroup: true,
+        text: "/admin",
+      }),
+      account: createAccount({
+        config: {
+          dmPolicy: "pairing",
+          allowFrom: [],
+          groupPolicy: "allowlist",
+          groupAllowFrom: ["bob!ident@example.com"],
+          groups: {
+            "#ops": {
+              allowFrom: ["alice!ident@example.com"],
+            },
+          },
+        },
+      }),
+      config: { channels: { irc: {} }, commands: { useAccessGroups: true } } as CoreConfig,
+      runtime,
+    });
+
+    expect(runtime.log).toHaveBeenCalledWith(
+      "irc: drop control command (unauthorized) target=alice!ident@example.com",
+    );
+  });
+
+  it("passes the shared reply pipeline for dispatched replies", async () => {
+    const coreRuntime = createPluginRuntimeMock();
+    setIrcRuntime(coreRuntime as never);
+
+    await handleIrcInbound({
+      message: createMessage(),
+      account: createAccount({
+        config: {
+          dmPolicy: "open",
+          allowFrom: ["*"],
+          groupPolicy: "allowlist",
+          groupAllowFrom: [],
+        },
+      }),
+      config: { channels: { irc: {} } } as CoreConfig,
+      runtime: createRuntimeEnv(),
+      sendReply: vi.fn(async () => {}),
+    });
+
+    const assembledRequest = (
+      coreRuntime.channel.inbound.dispatchReply as unknown as { mock: { calls: unknown[][] } }
+    ).mock.calls[0]?.[0] as { replyPipeline?: unknown } | undefined;
+    expect(assembledRequest?.replyPipeline).toEqual({});
+  });
+
+  it("uses channel:# prefix for group channel From and OriginatingTo fields", async () => {
+    const coreRuntime = createPluginRuntimeMock();
+    const runtime = createRuntimeEnv();
+    setIrcRuntime(coreRuntime as never);
+
+    await handleIrcInbound({
+      message: createMessage({
+        target: "#ops",
+        isGroup: true,
+        senderNick: "alice",
+        senderUser: "ident",
+        senderHost: "example.com",
+        text: "hello",
+      }),
+      account: createAccount({
+        config: {
+          dmPolicy: "open",
+          allowFrom: ["*"],
+          groupPolicy: "open",
+          groupAllowFrom: [],
+          groups: {
+            "#ops": { enabled: true, requireMention: false },
+          },
+        },
+      }),
+      config: { channels: { irc: {} } } as CoreConfig,
+      runtime,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    const ctx = (
+      coreRuntime.channel.reply.finalizeInboundContext as unknown as {
+        mock: { calls: unknown[][] };
+      }
+    ).mock.calls[0]?.[0] as Record<string, unknown> | undefined;
+    expect(
+      (coreRuntime.channel.inbound.dispatchReply as unknown as { mock: { calls: unknown[][] } })
+        .mock.calls.length,
+    ).toBe(1);
+    expect(runtime.log).not.toHaveBeenCalled();
+    expect(ctx?.From).toBe("channel:#ops");
+    expect(ctx?.To).toBe("channel:#ops");
+    expect(ctx?.OriginatingTo).toBe("channel:#ops");
+  });
+});