@actagent/irc 2026.6.2

package/src/client.ts

@@ -0,0 +1,443 @@
+// Irc plugin module implements client behavior.
+import net from "node:net";
+import tls from "node:tls";
+import { withTimeout } from "actagent/plugin-sdk/security-runtime";
+import { normalizeLowercaseStringOrEmpty } from "actagent/plugin-sdk/string-coerce-runtime";
+import {
+  parseIrcLine,
+  parseIrcPrefix,
+  sanitizeIrcOutboundText,
+  sanitizeIrcTarget,
+} from "./protocol.js";
+
+const IRC_ERROR_CODES = new Set(["432", "464", "465"]);
+const IRC_NICK_COLLISION_CODES = new Set(["433", "436"]);
+
+type IrcPrivmsgEvent = {
+  senderNick: string;
+  senderUser?: string;
+  senderHost?: string;
+  target: string;
+  text: string;
+  rawLine: string;
+};
+
+export type IrcClientOptions = {
+  host: string;
+  port: number;
+  tls: boolean;
+  nick: string;
+  username: string;
+  realname: string;
+  password?: string;
+  nickserv?: IrcNickServOptions;
+  channels?: string[];
+  connectTimeoutMs?: number;
+  messageChunkMaxChars?: number;
+  abortSignal?: AbortSignal;
+  onPrivmsg?: (event: IrcPrivmsgEvent) => void | Promise<void>;
+  onNotice?: (text: string, target?: string) => void;
+  onError?: (error: Error) => void;
+  onLine?: (line: string) => void;
+};
+
+type IrcNickServOptions = {
+  enabled?: boolean;
+  service?: string;
+  password?: string;
+  register?: boolean;
+  registerEmail?: string;
+};
+
+export type IrcClient = {
+  nick: string;
+  isReady: () => boolean;
+  sendRaw: (line: string) => void;
+  join: (channel: string) => void;
+  sendPrivmsg: (target: string, text: string) => void;
+  quit: (reason?: string) => void;
+  close: () => void;
+};
+
+function toError(err: unknown): Error {
+  if (err instanceof Error) {
+    return err;
+  }
+  return new Error(typeof err === "string" ? err : JSON.stringify(err));
+}
+
+function buildFallbackNick(nick: string): string {
+  const normalized = nick.replace(/\s+/g, "");
+  const safe = normalized.replace(/[^A-Za-z0-9_\-[\]\\`^{}|]/g, "");
+  const base = safe || "actagent";
+  const suffix = "_";
+  const maxNickLen = 30;
+  if (base.length >= maxNickLen) {
+    return `${base.slice(0, maxNickLen - suffix.length)}${suffix}`;
+  }
+  return `${base}${suffix}`;
+}
+
+function normalizeIrcNick(value: string): string {
+  return normalizeLowercaseStringOrEmpty(value);
+}
+
+export function buildIrcNickServCommands(options?: IrcNickServOptions): string[] {
+  if (!options || options.enabled === false) {
+    return [];
+  }
+  const password = sanitizeIrcOutboundText(options.password ?? "");
+  if (!password) {
+    return [];
+  }
+  const service = sanitizeIrcTarget(options.service?.trim() || "NickServ");
+  const commands = [`PRIVMSG ${service} :IDENTIFY ${password}`];
+  if (options.register) {
+    const registerEmail = sanitizeIrcOutboundText(options.registerEmail ?? "");
+    if (!registerEmail) {
+      throw new Error("IRC NickServ register requires registerEmail");
+    }
+    commands.push(`PRIVMSG ${service} :REGISTER ${password} ${registerEmail}`);
+  }
+  return commands;
+}
+
+export async function connectIrcClient(options: IrcClientOptions): Promise<IrcClient> {
+  const timeoutMs = options.connectTimeoutMs != null ? options.connectTimeoutMs : 15000;
+  const messageChunkMaxChars =
+    options.messageChunkMaxChars != null ? options.messageChunkMaxChars : 350;
+
+  if (!options.host.trim()) {
+    throw new Error("IRC host is required");
+  }
+  if (!options.nick.trim()) {
+    throw new Error("IRC nick is required");
+  }
+
+  const desiredNick = options.nick.trim();
+  let currentNick = desiredNick;
+  let ready = false;
+  let closed = false;
+  let nickServRecoverAttempted = false;
+  let fallbackNickAttempted = false;
+  let removeAbortListener: (() => void) | null = null;
+
+  const socket = options.tls
+    ? tls.connect({
+        host: options.host,
+        port: options.port,
+        servername: options.host,
+      })
+    : net.connect({ host: options.host, port: options.port });
+
+  socket.setEncoding("utf8");
+
+  let resolveReady: (() => void) | null = null;
+  let rejectReady: ((error: Error) => void) | null = null;
+  const readyPromise = new Promise<void>((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+
+  const fail = (err: unknown) => {
+    const error = toError(err);
+    if (options.onError) {
+      options.onError(error);
+    }
+    if (!ready && rejectReady) {
+      rejectReady(error);
+      rejectReady = null;
+      resolveReady = null;
+    }
+  };
+
+  const failAndClose = (err: unknown) => {
+    fail(err);
+    close();
+  };
+
+  const sendRaw = (line: string) => {
+    const cleaned = line.replace(/[\r\n]+/g, "").trim();
+    if (!cleaned) {
+      throw new Error("IRC command cannot be empty");
+    }
+    socket.write(`${cleaned}\r\n`);
+  };
+
+  const tryRecoverNickCollision = (): boolean => {
+    const nickServEnabled = options.nickserv?.enabled !== false;
+    const nickservPassword = sanitizeIrcOutboundText(options.nickserv?.password ?? "");
+    if (nickServEnabled && !nickServRecoverAttempted && nickservPassword) {
+      nickServRecoverAttempted = true;
+      try {
+        const service = sanitizeIrcTarget(options.nickserv?.service?.trim() || "NickServ");
+        sendRaw(`PRIVMSG ${service} :GHOST ${desiredNick} ${nickservPassword}`);
+        sendRaw(`NICK ${desiredNick}`);
+        return true;
+      } catch (err) {
+        fail(err);
+      }
+    }
+
+    if (!fallbackNickAttempted) {
+      fallbackNickAttempted = true;
+      const fallbackNick = buildFallbackNick(desiredNick);
+      if (normalizeIrcNick(fallbackNick) !== normalizeIrcNick(currentNick)) {
+        try {
+          sendRaw(`NICK ${fallbackNick}`);
+          currentNick = fallbackNick;
+          return true;
+        } catch (err) {
+          fail(err);
+        }
+      }
+    }
+    return false;
+  };
+
+  const join = (channel: string) => {
+    const target = sanitizeIrcTarget(channel);
+    if (!target.startsWith("#") && !target.startsWith("&")) {
+      throw new Error(`IRC JOIN target must be a channel: ${channel}`);
+    }
+    sendRaw(`JOIN ${target}`);
+  };
+
+  const sendPrivmsg = (target: string, text: string) => {
+    const normalizedTarget = sanitizeIrcTarget(target);
+    const cleaned = sanitizeIrcOutboundText(text);
+    if (!cleaned) {
+      return;
+    }
+    let remaining = cleaned;
+    while (remaining.length > 0) {
+      let chunk = remaining;
+      if (chunk.length > messageChunkMaxChars) {
+        let splitAt = chunk.lastIndexOf(" ", messageChunkMaxChars);
+        if (splitAt < Math.floor(messageChunkMaxChars / 2)) {
+          splitAt = messageChunkMaxChars;
+        }
+        chunk = chunk.slice(0, splitAt).trim();
+      }
+      if (!chunk) {
+        break;
+      }
+      sendRaw(`PRIVMSG ${normalizedTarget} :${chunk}`);
+      remaining = remaining.slice(chunk.length).trimStart();
+    }
+  };
+
+  const quit = (reason?: string) => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    removeAbortListener?.();
+    removeAbortListener = null;
+    const safeReason = sanitizeIrcOutboundText(reason != null ? reason : "bye");
+    try {
+      if (safeReason) {
+        sendRaw(`QUIT :${safeReason}`);
+      } else {
+        sendRaw("QUIT");
+      }
+    } catch {
+      // Ignore quit failures while shutting down.
+    }
+    socket.end();
+  };
+
+  const close = () => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    removeAbortListener?.();
+    removeAbortListener = null;
+    socket.destroy();
+  };
+
+  let buffer = "";
+  socket.on("data", (chunk: string) => {
+    buffer += chunk;
+    let idx = buffer.indexOf("\n");
+    while (idx !== -1) {
+      const rawLine = buffer.slice(0, idx).replace(/\r$/, "");
+      buffer = buffer.slice(idx + 1);
+      idx = buffer.indexOf("\n");
+
+      if (!rawLine) {
+        continue;
+      }
+      if (options.onLine) {
+        options.onLine(rawLine);
+      }
+
+      const line = parseIrcLine(rawLine);
+      if (!line) {
+        continue;
+      }
+
+      if (line.command === "PING") {
+        const payload =
+          line.trailing != null ? line.trailing : line.params[0] != null ? line.params[0] : "";
+        sendRaw(`PONG :${payload}`);
+        continue;
+      }
+
+      if (line.command === "NICK") {
+        const prefix = parseIrcPrefix(line.prefix);
+        if (prefix.nick && normalizeIrcNick(prefix.nick) === normalizeIrcNick(currentNick)) {
+          const next =
+            line.trailing != null
+              ? line.trailing
+              : line.params[0] != null
+                ? line.params[0]
+                : currentNick;
+          currentNick = next.trim();
+        }
+        continue;
+      }
+
+      if (!ready && IRC_NICK_COLLISION_CODES.has(line.command)) {
+        if (tryRecoverNickCollision()) {
+          continue;
+        }
+        const detail =
+          line.trailing != null ? line.trailing : line.params.join(" ") || "nickname in use";
+        fail(new Error(`IRC login failed (${line.command}): ${detail}`));
+        close();
+        return;
+      }
+
+      if (!ready && IRC_ERROR_CODES.has(line.command)) {
+        const detail =
+          line.trailing != null ? line.trailing : line.params.join(" ") || "login rejected";
+        fail(new Error(`IRC login failed (${line.command}): ${detail}`));
+        close();
+        return;
+      }
+
+      if (line.command === "001") {
+        ready = true;
+        const nickParam = line.params[0];
+        if (nickParam && nickParam.trim()) {
+          currentNick = nickParam.trim();
+        }
+        try {
+          const nickServCommands = buildIrcNickServCommands(options.nickserv);
+          for (const command of nickServCommands) {
+            sendRaw(command);
+          }
+        } catch (err) {
+          fail(err);
+        }
+        for (const channel of options.channels || []) {
+          const trimmed = channel.trim();
+          if (!trimmed) {
+            continue;
+          }
+          try {
+            join(trimmed);
+          } catch (err) {
+            fail(err);
+          }
+        }
+        if (resolveReady) {
+          resolveReady();
+        }
+        resolveReady = null;
+        rejectReady = null;
+        continue;
+      }
+
+      if (line.command === "NOTICE") {
+        if (options.onNotice) {
+          options.onNotice(line.trailing != null ? line.trailing : "", line.params[0]);
+        }
+        continue;
+      }
+
+      if (line.command === "PRIVMSG") {
+        const targetParam = line.params[0];
+        const target = targetParam ? targetParam.trim() : "";
+        const text = line.trailing != null ? line.trailing : "";
+        const prefix = parseIrcPrefix(line.prefix);
+        const senderNick = prefix.nick ? prefix.nick.trim() : "";
+        if (!target || !senderNick || !text.trim()) {
+          continue;
+        }
+        if (options.onPrivmsg) {
+          void Promise.resolve(
+            options.onPrivmsg({
+              senderNick,
+              senderUser: prefix.user ? prefix.user.trim() : undefined,
+              senderHost: prefix.host ? prefix.host.trim() : undefined,
+              target,
+              text,
+              rawLine,
+            }),
+          ).catch((error: unknown) => {
+            fail(error);
+          });
+        }
+      }
+    }
+  });
+
+  socket.once("connect", () => {
+    try {
+      if (options.password && options.password.trim()) {
+        sendRaw(`PASS ${options.password.trim()}`);
+      }
+      sendRaw(`NICK ${options.nick.trim()}`);
+      sendRaw(`USER ${options.username.trim()} 0 * :${sanitizeIrcOutboundText(options.realname)}`);
+    } catch (err) {
+      fail(err);
+      close();
+    }
+  });
+
+  socket.once("error", (err: unknown) => {
+    fail(err);
+  });
+
+  socket.once("close", () => {
+    if (!closed) {
+      closed = true;
+      if (!ready) {
+        fail(new Error("IRC connection closed before ready"));
+      }
+    }
+  });
+
+  if (options.abortSignal) {
+    const abort = () => {
+      if (!ready) {
+        failAndClose(new Error("IRC connect aborted"));
+        return;
+      }
+      quit("shutdown");
+    };
+    if (options.abortSignal.aborted) {
+      abort();
+    } else {
+      options.abortSignal.addEventListener("abort", abort, { once: true });
+      removeAbortListener = () => options.abortSignal?.removeEventListener("abort", abort);
+    }
+  }
+
+  await withTimeout(readyPromise, timeoutMs, "IRC connect");
+
+  return {
+    get nick() {
+      return currentNick;
+    },
+    isReady: () => ready && !closed,
+    sendRaw,
+    join,
+    sendPrivmsg,
+    quit,
+    close,
+  };
+}

package/src/config-schema.test.ts

@@ -0,0 +1,117 @@
+// Irc tests cover config schema plugin behavior.
+import { describe, expect, it } from "vitest";
+import { IrcConfigSchema } from "./config-schema.js";
+
+function expectValidConfig(result: ReturnType<typeof IrcConfigSchema.safeParse>) {
+  expect(result.success).toBe(true);
+  if (!result.success) {
+    throw new Error("expected config to be valid");
+  }
+  return result.data;
+}
+
+function expectInvalidConfig(result: ReturnType<typeof IrcConfigSchema.safeParse>) {
+  expect(result.success).toBe(false);
+  if (result.success) {
+    throw new Error("expected config to be invalid");
+  }
+  return result.error.issues;
+}
+
+describe("irc config schema", () => {
+  it("accepts basic config", () => {
+    const config = expectValidConfig(
+      IrcConfigSchema.safeParse({
+        host: "irc.libera.chat",
+        nick: "actagent-bot",
+        channels: ["#actagent"],
+      }),
+    );
+
+    expect(config.host).toBe("irc.libera.chat");
+    expect(config.nick).toBe("actagent-bot");
+  });
+
+  it('rejects dmPolicy="open" without allowFrom "*"', () => {
+    const issues = expectInvalidConfig(
+      IrcConfigSchema.safeParse({
+        dmPolicy: "open",
+        allowFrom: ["alice"],
+      }),
+    );
+
+    expect(issues[0]?.path.join(".")).toBe("allowFrom");
+  });
+
+  it('accepts dmPolicy="open" with allowFrom "*"', () => {
+    const config = expectValidConfig(
+      IrcConfigSchema.safeParse({
+        dmPolicy: "open",
+        allowFrom: ["*"],
+      }),
+    );
+
+    expect(config.dmPolicy).toBe("open");
+  });
+
+  it("accepts numeric allowFrom and groupAllowFrom entries", () => {
+    const parsed = IrcConfigSchema.parse({
+      dmPolicy: "allowlist",
+      allowFrom: [12345, "alice"],
+      groupAllowFrom: [67890, "alice!ident@example.org"],
+    });
+
+    expect(parsed.allowFrom).toEqual([12345, "alice"]);
+    expect(parsed.groupAllowFrom).toEqual([67890, "alice!ident@example.org"]);
+  });
+
+  it("accepts numeric per-channel allowFrom entries", () => {
+    const parsed = IrcConfigSchema.parse({
+      groups: {
+        "#ops": {
+          allowFrom: [42, "alice"],
+        },
+      },
+    });
+
+    expect(parsed.groups?.["#ops"]?.allowFrom).toEqual([42, "alice"]);
+  });
+
+  it("rejects nickserv register without registerEmail", () => {
+    const issues = expectInvalidConfig(
+      IrcConfigSchema.safeParse({
+        nickserv: {
+          register: true,
+          password: "secret",
+        },
+      }),
+    );
+
+    expect(issues[0]?.path.join(".")).toBe("nickserv.registerEmail");
+  });
+
+  it("accepts nickserv register with password and registerEmail", () => {
+    const config = expectValidConfig(
+      IrcConfigSchema.safeParse({
+        nickserv: {
+          register: true,
+          password: "secret",
+          registerEmail: "bot@example.com",
+        },
+      }),
+    );
+
+    expect(config.nickserv?.register).toBe(true);
+  });
+
+  it("accepts nickserv register with registerEmail only", () => {
+    expectValidConfig(
+      IrcConfigSchema.safeParse({
+        nickserv: {
+          register: true,
+          registerEmail: "bot@example.com",
+        },
+      }),
+    );
+  });
+});

package/src/config-schema.ts

@@ -0,0 +1,97 @@
+// Irc helper module supports config schema behavior.
+import {
+  DmPolicySchema,
+  GroupPolicySchema,
+  MarkdownConfigSchema,
+  ReplyRuntimeConfigSchemaShape,
+  ToolPolicySchema,
+  buildChannelConfigSchema,
+  requireOpenAllowFrom,
+} from "actagent/plugin-sdk/channel-config-schema";
+import { z } from "zod";
+import { ircChannelConfigUiHints } from "./config-ui-hints.js";
+
+const IrcGroupSchema = z
+  .object({
+    requireMention: z.boolean().optional(),
+    tools: ToolPolicySchema,
+    toolsBySender: z.record(z.string(), ToolPolicySchema).optional(),
+    skills: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    systemPrompt: z.string().optional(),
+  })
+  .strict();
+
+const IrcNickServSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    service: z.string().optional(),
+    password: z.string().optional(),
+    passwordFile: z.string().optional(),
+    register: z.boolean().optional(),
+    registerEmail: z.string().optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.register && !value.registerEmail?.trim()) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["registerEmail"],
+        message: "channels.irc.nickserv.register=true requires channels.irc.nickserv.registerEmail",
+      });
+    }
+  });
+
+const IrcAccountSchemaBase = z
+  .object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    dangerouslyAllowNameMatching: z.boolean().optional(),
+    host: z.string().optional(),
+    port: z.number().int().min(1).max(65535).optional(),
+    tls: z.boolean().optional(),
+    nick: z.string().optional(),
+    username: z.string().optional(),
+    realname: z.string().optional(),
+    password: z.string().optional(),
+    passwordFile: z.string().optional(),
+    nickserv: IrcNickServSchema.optional(),
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groupPolicy: GroupPolicySchema.optional().default("allowlist"),
+    groupAllowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groups: z.record(z.string(), IrcGroupSchema.optional()).optional(),
+    channels: z.array(z.string()).optional(),
+    mentionPatterns: z.array(z.string()).optional(),
+    markdown: MarkdownConfigSchema,
+    ...ReplyRuntimeConfigSchemaShape,
+  })
+  .strict();
+
+const IrcAccountSchema = IrcAccountSchemaBase.superRefine((value, ctx) => {
+  requireOpenAllowFrom({
+    policy: value.dmPolicy,
+    allowFrom: value.allowFrom,
+    ctx,
+    path: ["allowFrom"],
+    message: 'channels.irc.dmPolicy="open" requires channels.irc.allowFrom to include "*"',
+  });
+});
+
+export const IrcConfigSchema = IrcAccountSchemaBase.extend({
+  accounts: z.record(z.string(), IrcAccountSchema.optional()).optional(),
+  defaultAccount: z.string().optional(),
+}).superRefine((value, ctx) => {
+  requireOpenAllowFrom({
+    policy: value.dmPolicy,
+    allowFrom: value.allowFrom,
+    ctx,
+    path: ["allowFrom"],
+    message: 'channels.irc.dmPolicy="open" requires channels.irc.allowFrom to include "*"',
+  });
+});
+
+export const IrcChannelConfigSchema = buildChannelConfigSchema(IrcConfigSchema, {
+  uiHints: ircChannelConfigUiHints,
+});

package/src/config-ui-hints.ts

@@ -0,0 +1,41 @@
+// Irc helper module supports config ui hints behavior.
+import type { ChannelConfigUiHint } from "actagent/plugin-sdk/core";
+
+export const ircChannelConfigUiHints = {
+  "": {
+    label: "IRC",
+    help: "IRC channel provider configuration and compatibility settings for classic IRC transport workflows. Use this section when bridging legacy chat infrastructure into ACTAgent.",
+  },
+  dmPolicy: {
+    label: "IRC DM Policy",
+    help: 'Direct message access control ("pairing" recommended). "open" requires channels.irc.allowFrom=["*"].',
+  },
+  "nickserv.enabled": {
+    label: "IRC NickServ Enabled",
+    help: "Enable NickServ identify/register after connect (defaults to enabled when password is configured).",
+  },
+  "nickserv.service": {
+    label: "IRC NickServ Service",
+    help: "NickServ service nick (default: NickServ).",
+  },
+  "nickserv.password": {
+    label: "IRC NickServ Password",
+    help: "NickServ password used for IDENTIFY/REGISTER (sensitive).",
+  },
+  "nickserv.passwordFile": {
+    label: "IRC NickServ Password File",
+    help: "Optional file path containing NickServ password.",
+  },
+  "nickserv.register": {
+    label: "IRC NickServ Register",
+    help: "If true, send NickServ REGISTER on every connect. Use once for initial registration, then disable.",
+  },
+  "nickserv.registerEmail": {
+    label: "IRC NickServ Register Email",
+    help: "Email used with NickServ REGISTER (required when register=true).",
+  },
+  configWrites: {
+    label: "IRC Config Writes",
+    help: "Allow IRC to write config in response to channel events/commands (default: true).",
+  },
+} satisfies Record<string, ChannelConfigUiHint>;