@actagent/irc 2026.6.2

package/src/normalize.test.ts

@@ -0,0 +1,56 @@
+// Irc tests cover normalize plugin behavior.
+import { describe, expect, it } from "vitest";
+import {
+  buildIrcAllowlistCandidates,
+  normalizeIrcAllowEntry,
+  normalizeIrcMessagingTarget,
+  resolveIrcAllowlistMatch,
+} from "./normalize.js";
+
+describe("irc normalize", () => {
+  it("normalizes targets", () => {
+    expect(normalizeIrcMessagingTarget("irc:channel:actagent")).toBe("#actagent");
+    expect(normalizeIrcMessagingTarget("user:alice")).toBe("alice");
+    expect(normalizeIrcMessagingTarget("\n")).toBeUndefined();
+  });
+
+  it("normalizes allowlist entries", () => {
+    expect(normalizeIrcAllowEntry("IRC:User:Alice!u@h")).toBe("alice!u@h");
+  });
+
+  it("matches senders by nick/user/host candidates", () => {
+    const message = {
+      messageId: "m1",
+      target: "#chan",
+      senderNick: "Alice",
+      senderUser: "ident",
+      senderHost: "example.org",
+      text: "hi",
+      timestamp: Date.now(),
+      isGroup: true,
+    };
+
+    expect(buildIrcAllowlistCandidates(message)).toContain("alice!ident@example.org");
+    expect(buildIrcAllowlistCandidates(message)).not.toContain("alice");
+    expect(buildIrcAllowlistCandidates(message, { allowNameMatching: true })).toContain("alice");
+    expect(
+      resolveIrcAllowlistMatch({
+        allowFrom: ["alice!ident@example.org"],
+        message,
+      }).allowed,
+    ).toBe(true);
+    expect(
+      resolveIrcAllowlistMatch({
+        allowFrom: ["alice"],
+        message,
+      }).allowed,
+    ).toBe(false);
+    expect(
+      resolveIrcAllowlistMatch({
+        allowFrom: ["alice"],
+        message,
+        allowNameMatching: true,
+      }).allowed,
+    ).toBe(true);
+  });
+});

package/src/normalize.ts

@@ -0,0 +1,111 @@
+// Irc helper module supports normalize behavior.
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalLowercaseString,
+  normalizeStringEntriesLower,
+} from "actagent/plugin-sdk/string-coerce-runtime";
+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 = normalizeLowercaseStringOrEmpty(target);
+  if (lowered.startsWith("irc:")) {
+    target = target.slice("irc:".length).trim();
+  }
+  if (normalizeLowercaseStringOrEmpty(target).startsWith("channel:")) {
+    target = target.slice("channel:".length).trim();
+    if (!target.startsWith("#") && !target.startsWith("&")) {
+      target = `#${target}`;
+    }
+  }
+  if (normalizeLowercaseStringOrEmpty(target).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 = normalizeLowercaseStringOrEmpty(raw);
+  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 buildIrcAllowlistCandidates(
+  message: IrcInboundMessage,
+  params?: { allowNameMatching?: boolean },
+): string[] {
+  const nick = normalizeLowercaseStringOrEmpty(message.senderNick);
+  const user = normalizeOptionalLowercaseString(message.senderUser);
+  const host = normalizeOptionalLowercaseString(message.senderHost);
+  const candidates = new Set<string>();
+  if (nick && params?.allowNameMatching === true) {
+    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;
+  allowNameMatching?: boolean;
+}): { allowed: boolean; source?: string } {
+  const allowFrom = new Set(normalizeStringEntriesLower(params.allowFrom));
+  if (allowFrom.has("*")) {
+    return { allowed: true, source: "wildcard" };
+  }
+  const candidates = buildIrcAllowlistCandidates(params.message, {
+    allowNameMatching: params.allowNameMatching,
+  });
+  for (const candidate of candidates) {
+    if (allowFrom.has(candidate)) {
+      return { allowed: true, source: candidate };
+    }
+  }
+  return { allowed: false };
+}

package/src/outbound-base.ts

@@ -0,0 +1,11 @@
+// Irc plugin module implements outbound base behavior.
+import { sanitizeForPlainText } from "actagent/plugin-sdk/channel-outbound";
+import { chunkTextForOutbound } from "./channel-api.js";
+
+export const ircOutboundBaseAdapter = {
+  deliveryMode: "direct" as const,
+  chunker: chunkTextForOutbound,
+  chunkerMode: "markdown" as const,
+  textChunkLimit: 350,
+  sanitizeText: ({ text }: { text: string }) => sanitizeForPlainText(text),
+};

package/src/policy.test.ts

@@ -0,0 +1,56 @@
+// Irc tests cover policy plugin behavior.
+import { resolveChannelGroupPolicy } from "actagent/plugin-sdk/channel-policy";
+import { describe, expect, it } from "vitest";
+import { resolveIrcGroupMatch, resolveIrcRequireMention } from "./policy.js";
+
+describe("irc policy", () => {
+  it("matches direct and wildcard group entries", () => {
+    const direct = resolveIrcGroupMatch({
+      groups: {
+        "#ops": { requireMention: false },
+      },
+      target: "#ops",
+    });
+    expect(direct.allowed).toBe(true);
+    expect(resolveIrcRequireMention({ groupConfig: direct.groupConfig })).toBe(false);
+
+    const wildcard = resolveIrcGroupMatch({
+      groups: {
+        "*": { requireMention: true },
+      },
+      target: "#random",
+    });
+    expect(wildcard.allowed).toBe(true);
+    expect(resolveIrcRequireMention({ wildcardConfig: wildcard.wildcardConfig })).toBe(true);
+  });
+
+  it("keeps case-insensitive group matching aligned with shared channel policy resolution", () => {
+    const groups = {
+      "#Ops": { requireMention: false },
+      "#Hidden": { enabled: false },
+      "*": { requireMention: true },
+    };
+
+    const inboundDirect = resolveIrcGroupMatch({ groups, target: "#ops" });
+    const sharedDirect = resolveChannelGroupPolicy({
+      cfg: { channels: { irc: { groups } } },
+      channel: "irc",
+      groupId: "#ops",
+      groupIdCaseInsensitive: true,
+    });
+    expect(sharedDirect.allowed).toBe(inboundDirect.allowed);
+    expect(sharedDirect.groupConfig?.requireMention).toBe(
+      inboundDirect.groupConfig?.requireMention,
+    );
+
+    const inboundDisabled = resolveIrcGroupMatch({ groups, target: "#hidden" });
+    const sharedDisabled = resolveChannelGroupPolicy({
+      cfg: { channels: { irc: { groups } } },
+      channel: "irc",
+      groupId: "#hidden",
+      groupIdCaseInsensitive: true,
+    });
+    expect(sharedDisabled.allowed).toBe(inboundDisabled.allowed);
+    expect(inboundDisabled.groupConfig?.enabled).toBe(false);
+  });
+});

package/src/policy.ts

@@ -0,0 +1,79 @@
+// Irc plugin module implements policy behavior.
+import { normalizeLowercaseStringOrEmpty } from "actagent/plugin-sdk/string-coerce-runtime";
+import type { IrcChannelConfig } from "./types.js";
+
+export type IrcGroupMatch = {
+  allowed: boolean;
+  groupConfig?: IrcChannelConfig;
+  wildcardConfig?: IrcChannelConfig;
+  hasConfiguredGroups: boolean;
+};
+
+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 represented later as ingress route facts.
+      allowed: true,
+      groupConfig: direct,
+      wildcardConfig: groups["*"],
+      hasConfiguredGroups,
+    };
+  }
+
+  const targetLower = normalizeLowercaseStringOrEmpty(params.target);
+  const directKey = Object.keys(groups).find(
+    (key) => normalizeLowercaseStringOrEmpty(key) === targetLower,
+  );
+  if (directKey) {
+    const matched = groups[directKey];
+    if (matched) {
+      return {
+        // "allowed" means the target matched an allowlisted key.
+        // Explicit disables are represented later as ingress route facts.
+        allowed: true,
+        groupConfig: matched,
+        wildcardConfig: groups["*"],
+        hasConfiguredGroups,
+      };
+    }
+  }
+
+  const wildcard = groups["*"];
+  if (wildcard) {
+    return {
+      // "allowed" means the target matched an allowlisted key.
+      // Explicit disables are represented later as ingress route facts.
+      allowed: true,
+      wildcardConfig: wildcard,
+      hasConfiguredGroups,
+    };
+  }
+  return {
+    allowed: false,
+    hasConfiguredGroups,
+  };
+}
+
+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;
+}

package/src/probe.test.ts

@@ -0,0 +1,111 @@
+// Irc tests cover probe plugin behavior.
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { probeIrc } from "./probe.js";
+
+const resolveIrcAccountMock = vi.hoisted(() => vi.fn());
+const buildIrcConnectOptionsMock = vi.hoisted(() => vi.fn());
+const connectIrcClientMock = vi.hoisted(() => vi.fn());
+
+vi.mock("./accounts.js", () => ({
+  resolveIrcAccount: resolveIrcAccountMock,
+}));
+
+vi.mock("./connect-options.js", () => ({
+  buildIrcConnectOptions: buildIrcConnectOptionsMock,
+}));
+
+vi.mock("./client.js", () => ({
+  connectIrcClient: connectIrcClientMock,
+}));
+
+afterAll(() => {
+  vi.doUnmock("./accounts.js");
+  vi.doUnmock("./connect-options.js");
+  vi.doUnmock("./client.js");
+  vi.resetModules();
+});
+
+describe("probeIrc", () => {
+  beforeEach(() => {
+    resolveIrcAccountMock.mockReset();
+    buildIrcConnectOptionsMock.mockReset();
+    connectIrcClientMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns a configuration error when the IRC account is incomplete", async () => {
+    resolveIrcAccountMock.mockReturnValue({
+      configured: false,
+      host: "",
+      port: 6667,
+      tls: false,
+      nick: "",
+    });
+
+    await expect(probeIrc({} as never)).resolves.toEqual({
+      ok: false,
+      host: "",
+      port: 6667,
+      tls: false,
+      nick: "",
+      error: "missing host or nick",
+    });
+    expect(connectIrcClientMock).not.toHaveBeenCalled();
+  });
+
+  it("returns latency and quits the probe client on success", async () => {
+    const account = {
+      configured: true,
+      host: "irc.libera.chat",
+      port: 6697,
+      tls: true,
+      nick: "actagent",
+    };
+    resolveIrcAccountMock.mockReturnValue(account);
+    buildIrcConnectOptionsMock.mockReturnValue({ host: "irc.libera.chat" });
+    const quit = vi.fn();
+    connectIrcClientMock.mockResolvedValue({ quit });
+    const nowSpy = vi.spyOn(Date, "now").mockReturnValueOnce(100).mockReturnValueOnce(145);
+
+    try {
+      const result = await probeIrc({} as never, { timeoutMs: 5000 });
+
+      expect(buildIrcConnectOptionsMock).toHaveBeenCalledWith(account, { connectTimeoutMs: 5000 });
+      expect(result).toEqual({
+        ok: true,
+        host: "irc.libera.chat",
+        port: 6697,
+        tls: true,
+        nick: "actagent",
+        latencyMs: 45,
+      });
+      expect(quit).toHaveBeenCalledWith("probe");
+    } finally {
+      nowSpy.mockRestore();
+    }
+  });
+
+  it("formats non-Error probe failures into the returned error field", async () => {
+    resolveIrcAccountMock.mockReturnValue({
+      configured: true,
+      host: "irc.libera.chat",
+      port: 6667,
+      tls: false,
+      nick: "actagent",
+    });
+    buildIrcConnectOptionsMock.mockReturnValue({ host: "irc.libera.chat" });
+    connectIrcClientMock.mockRejectedValue({ code: "ECONNREFUSED" });
+
+    await expect(probeIrc({} as never)).resolves.toEqual({
+      ok: false,
+      host: "irc.libera.chat",
+      port: 6667,
+      tls: false,
+      nick: "actagent",
+      error: JSON.stringify({ code: "ECONNREFUSED" }),
+    });
+  });
+});

package/src/probe.ts

@@ -0,0 +1,54 @@
+// Irc plugin module implements probe behavior.
+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),
+    };
+  }
+}

package/src/protocol.test.ts

@@ -0,0 +1,49 @@
+// Irc tests cover protocol plugin behavior.
+import { describe, expect, it } from "vitest";
+import {
+  parseIrcLine,
+  parseIrcPrefix,
+  sanitizeIrcOutboundText,
+  sanitizeIrcTarget,
+  splitIrcText,
+} from "./protocol.js";
+
+describe("irc protocol", () => {
+  it("parses PRIVMSG lines with prefix and trailing", () => {
+    const parsed = parseIrcLine(":alice!u@host PRIVMSG #room :hello world");
+    expect(parsed).toEqual({
+      raw: ":alice!u@host PRIVMSG #room :hello world",
+      prefix: "alice!u@host",
+      command: "PRIVMSG",
+      params: ["#room"],
+      trailing: "hello world",
+    });
+
+    expect(parseIrcPrefix(parsed?.prefix)).toEqual({
+      nick: "alice",
+      user: "u",
+      host: "host",
+    });
+  });
+
+  it("sanitizes outbound text to prevent command injection", () => {
+    expect(sanitizeIrcOutboundText("hello\\r\\nJOIN #oops")).toBe("hello JOIN #oops");
+    expect(sanitizeIrcOutboundText("\\u0001test\\u0000")).toBe("test");
+  });
+
+  it("validates targets and rejects control characters", () => {
+    expect(sanitizeIrcTarget("#actagent")).toBe("#actagent");
+    expect(() => sanitizeIrcTarget("#bad\\nPING")).toThrow(/Invalid IRC target/);
+    expect(() => sanitizeIrcTarget(" user")).toThrow(/Invalid IRC target/);
+  });
+
+  it("splits long text on boundaries", () => {
+    const chunks = splitIrcText("a ".repeat(300), 120);
+    expect(chunks.length).toBeGreaterThan(2);
+    expect(
+      chunks
+        .map((chunk, index) => ({ index, length: chunk.length }))
+        .filter((chunk) => chunk.length > 120),
+    ).toStrictEqual([]);
+  });
+});

package/src/protocol.ts

@@ -0,0 +1,170 @@
+// Irc plugin module implements protocol behavior.
+import { randomUUID } from "node:crypto";
+import { hasIrcControlChars, stripIrcControlChars } from "./control-chars.js";
+
+const IRC_TARGET_PATTERN = /^[^\s:]+$/u;
+
+type ParsedIrcLine = {
+  raw: string;
+  prefix?: string;
+  command: string;
+  params: string[];
+  trailing?: string;
+};
+
+type ParsedIrcPrefix = {
+  nick?: string;
+  user?: string;
+  host?: string;
+  server?: string;
+};
+
+export function parseIrcLine(line: string): ParsedIrcLine | null {
+  const raw = line.replace(/[\r\n]+/g, "").trim();
+  if (!raw) {
+    return null;
+  }
+
+  let cursor = raw;
+  let prefix: string | undefined;
+  if (cursor.startsWith(":")) {
+    const idx = cursor.indexOf(" ");
+    if (idx <= 1) {
+      return null;
+    }
+    prefix = cursor.slice(1, idx);
+    cursor = cursor.slice(idx + 1).trimStart();
+  }
+
+  if (!cursor) {
+    return null;
+  }
+
+  const firstSpace = cursor.indexOf(" ");
+  const command = (firstSpace === -1 ? cursor : cursor.slice(0, firstSpace)).trim();
+  if (!command) {
+    return null;
+  }
+
+  cursor = firstSpace === -1 ? "" : cursor.slice(firstSpace + 1);
+  const params: string[] = [];
+  let trailing: string | undefined;
+
+  while (cursor.length > 0) {
+    cursor = cursor.trimStart();
+    if (!cursor) {
+      break;
+    }
+    if (cursor.startsWith(":")) {
+      trailing = cursor.slice(1);
+      break;
+    }
+    const spaceIdx = cursor.indexOf(" ");
+    if (spaceIdx === -1) {
+      params.push(cursor);
+      break;
+    }
+    params.push(cursor.slice(0, spaceIdx));
+    cursor = cursor.slice(spaceIdx + 1);
+  }
+
+  return {
+    raw,
+    prefix,
+    command: command.toUpperCase(),
+    params,
+    trailing,
+  };
+}
+
+export function parseIrcPrefix(prefix?: string): ParsedIrcPrefix {
+  if (!prefix) {
+    return {};
+  }
+  const nickPart = prefix.match(/^([^!@]+)!([^@]+)@(.+)$/);
+  if (nickPart) {
+    return {
+      nick: nickPart[1],
+      user: nickPart[2],
+      host: nickPart[3],
+    };
+  }
+  const nickHostPart = prefix.match(/^([^@]+)@(.+)$/);
+  if (nickHostPart) {
+    return {
+      nick: nickHostPart[1],
+      host: nickHostPart[2],
+    };
+  }
+  if (prefix.includes("!")) {
+    const [nick, user] = prefix.split("!", 2);
+    return { nick, user };
+  }
+  if (prefix.includes(".")) {
+    return { server: prefix };
+  }
+  return { nick: prefix };
+}
+
+function decodeLiteralEscapes(input: string): string {
+  // Defensive: this is not a full JS string unescaper.
+  // It's just enough to catch common "\r\n" / "\u0001" style payloads.
+  return input
+    .replace(/\\r/g, "\r")
+    .replace(/\\n/g, "\n")
+    .replace(/\\t/g, "\t")
+    .replace(/\\0/g, "\0")
+    .replace(/\\x([0-9a-fA-F]{2})/g, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+    .replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+}
+
+export function sanitizeIrcOutboundText(text: string): string {
+  const decoded = decodeLiteralEscapes(text);
+  return stripIrcControlChars(decoded.replace(/\r?\n/g, " ")).trim();
+}
+
+export function sanitizeIrcTarget(raw: string): string {
+  const decoded = decodeLiteralEscapes(raw);
+  if (!decoded) {
+    throw new Error("IRC target is required");
+  }
+  // Reject any surrounding whitespace instead of trimming it away.
+  if (decoded !== decoded.trim()) {
+    throw new Error(`Invalid IRC target: ${raw}`);
+  }
+  if (hasIrcControlChars(decoded)) {
+    throw new Error(`Invalid IRC target: ${raw}`);
+  }
+  if (!IRC_TARGET_PATTERN.test(decoded)) {
+    throw new Error(`Invalid IRC target: ${raw}`);
+  }
+  return decoded;
+}
+
+export function splitIrcText(text: string, maxChars = 350): string[] {
+  const cleaned = sanitizeIrcOutboundText(text);
+  if (!cleaned) {
+    return [];
+  }
+  if (cleaned.length <= maxChars) {
+    return [cleaned];
+  }
+  const chunks: string[] = [];
+  let remaining = cleaned;
+  while (remaining.length > maxChars) {
+    let splitAt = remaining.lastIndexOf(" ", maxChars);
+    if (splitAt < Math.floor(maxChars * 0.5)) {
+      splitAt = maxChars;
+    }
+    chunks.push(remaining.slice(0, splitAt).trim());
+    remaining = remaining.slice(splitAt).trimStart();
+  }
+  if (remaining) {
+    chunks.push(remaining);
+  }
+  return chunks.filter(Boolean);
+}
+
+export function makeIrcMessageId() {
+  return randomUUID();
+}