@actagent/irc 2026.6.2

package/actagent.plugin.json

@@ -0,0 +1,26 @@
+{
+  "id": "irc",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["irc"],
+  "channelEnvVars": {
+    "irc": [
+      "IRC_HOST",
+      "IRC_PORT",
+      "IRC_TLS",
+      "IRC_NICK",
+      "IRC_USERNAME",
+      "IRC_REALNAME",
+      "IRC_PASSWORD",
+      "IRC_CHANNELS",
+      "IRC_NICKSERV_PASSWORD",
+      "IRC_NICKSERV_REGISTER_EMAIL"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/api.ts

@@ -0,0 +1,11 @@
+// Irc API module exposes the plugin public contract.
+export { ircPlugin } from "./src/channel.js";
+export { setIrcRuntime } from "./src/runtime.js";
+export {
+  listEnabledIrcAccounts,
+  listIrcAccountIds,
+  resolveDefaultIrcAccountId,
+  type ResolvedIrcAccount,
+  resolveIrcAccount,
+} from "./src/accounts.js";
+export { ircSetupAdapter, ircSetupWizard } from "./src/setup-surface.js";

package/channel-config-api.ts

@@ -0,0 +1,2 @@
+// Irc API module exposes the plugin public contract.
+export { IrcChannelConfigSchema } from "./src/config-schema.js";

package/channel-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled channel entry imports narrow so bootstrap/discovery paths do
+// not drag IRC runtime/send/monitor surfaces into lightweight plugin loads.
+export { ircPlugin } from "./src/channel.js";

package/configured-state.ts

@@ -0,0 +1,9 @@
+// Irc helper module supports configured state behavior.
+export function hasIrcConfiguredState(params: { env?: NodeJS.ProcessEnv }): boolean {
+  return (
+    typeof params.env?.IRC_HOST === "string" &&
+    params.env.IRC_HOST.trim().length > 0 &&
+    typeof params.env?.IRC_NICK === "string" &&
+    params.env.IRC_NICK.trim().length > 0
+  );
+}

package/contract-api.ts

@@ -0,0 +1,5 @@
+// Irc API module exposes the plugin public contract.
+export {
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/index.test.ts

@@ -0,0 +1,14 @@
+// Irc tests cover index plugin behavior.
+import { assertBundledChannelEntries } from "actagent/plugin-sdk/channel-test-helpers";
+import { describe } from "vitest";
+import entry from "./index.js";
+import setupEntry from "./setup-entry.js";
+
+describe("irc bundled entries", () => {
+  assertBundledChannelEntries({
+    entry,
+    expectedId: "irc",
+    expectedName: "IRC",
+    setupEntry,
+  });
+});

package/index.ts

@@ -0,0 +1,21 @@
+// Irc plugin entrypoint registers its ACTAgent integration.
+import { defineBundledChannelEntry } from "actagent/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelEntry({
+  id: "irc",
+  name: "IRC",
+  description: "IRC channel plugin",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "ircPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setIrcRuntime",
+  },
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@actagent/irc",
+  "version": "2026.6.2",
+  "description": "ACTAgent IRC channel plugin",
+  "type": "module",
+  "devDependencies": {
+    "@actagent/plugin-sdk": "workspace:*"
+  },
+  "actagent": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "minHostVersion": ">=2026.4.10"
+    },
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "irc",
+      "label": "IRC",
+      "selectionLabel": "IRC (Server + Nick)",
+      "detailLabel": "IRC",
+      "docsPath": "/channels/irc",
+      "docsLabel": "irc",
+      "blurb": "classic IRC networks with DM/channel routing and pairing controls.",
+      "aliases": [
+        "internet-relay-chat"
+      ],
+      "systemImage": "network",
+      "configuredState": {
+        "env": {
+          "allOf": [
+            "IRC_HOST",
+            "IRC_NICK"
+          ]
+        },
+        "specifier": "./configured-state",
+        "exportName": "hasIrcConfiguredState"
+      }
+    }
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  }
+}

package/runtime-api.test.ts

@@ -0,0 +1,24 @@
+// Irc tests cover runtime api plugin behavior.
+import { runDirectImportSmoke } from "actagent/plugin-sdk/plugin-test-contracts";
+import { beforeAll, describe, expect, it } from "vitest";
+
+describe("irc bundled api seams", () => {
+  let directSmokeStdout = "";
+
+  beforeAll(async () => {
+    directSmokeStdout = await runDirectImportSmoke(
+      `const channel = await import("./extensions/irc/channel-plugin-api.ts");
+const runtime = await import("./extensions/irc/runtime-api.ts");
+process.stdout.write(JSON.stringify({
+  channel: { keys: Object.keys(channel).sort(), id: channel.ircPlugin.id },
+  runtime: { keys: Object.keys(runtime).sort(), type: typeof runtime.setIrcRuntime },
+}));`,
+    );
+  }, 45_000);
+
+  it("loads narrow public api modules in direct smoke", () => {
+    expect(directSmokeStdout).toBe(
+      '{"channel":{"keys":["ircPlugin"],"id":"irc"},"runtime":{"keys":["setIrcRuntime"],"type":"function"}}',
+    );
+  });
+});

package/runtime-api.ts

@@ -0,0 +1,3 @@
+// Keep the bundled runtime entry narrow so generic runtime activation does not
+// import the broad IRC API barrel just to install runtime state.
+export { setIrcRuntime } from "./src/runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,6 @@
+// Irc API module exposes the plugin public contract.
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-entry.ts

@@ -0,0 +1,14 @@
+// Irc plugin module implements setup entry behavior.
+import { defineBundledChannelSetupEntry } from "actagent/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "ircPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});

package/src/accounts.test.ts

@@ -0,0 +1,224 @@
+// Irc tests cover accounts plugin behavior.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import { listIrcAccountIds, resolveDefaultIrcAccountId, resolveIrcAccount } from "./accounts.js";
+import type { CoreConfig } from "./types.js";
+
+function asConfig(value: unknown): CoreConfig {
+  return value as CoreConfig;
+}
+
+describe("listIrcAccountIds", () => {
+  it("returns default when no accounts are configured", () => {
+    expect(listIrcAccountIds(asConfig({}))).toEqual(["default"]);
+  });
+
+  it("normalizes, deduplicates, and sorts configured account ids", () => {
+    const cfg = asConfig({
+      channels: {
+        irc: {
+          accounts: {
+            "Ops Team": {},
+            "ops-team": {},
+            Work: {},
+          },
+        },
+      },
+    });
+
+    expect(listIrcAccountIds(cfg)).toEqual(["ops-team", "work"]);
+  });
+
+  it("keeps the implicit default account when named accounts are added to top-level connection config", () => {
+    const cfg = asConfig({
+      channels: {
+        irc: {
+          host: "irc.example.com",
+          nick: "actagent",
+          accounts: {
+            work: {
+              enabled: false,
+              host: "irc-work.example.com",
+              nick: "actagent-work",
+            },
+          },
+        },
+      },
+    });
+
+    expect(listIrcAccountIds(cfg)).toEqual(["default", "work"]);
+    expect(resolveDefaultIrcAccountId(cfg)).toBe("default");
+  });
+});
+
+describe("resolveDefaultIrcAccountId", () => {
+  it("prefers configured defaultAccount when it matches", () => {
+    const cfg = asConfig({
+      channels: {
+        irc: {
+          defaultAccount: "Ops Team",
+          accounts: {
+            default: {},
+            "ops-team": {},
+          },
+        },
+      },
+    });
+
+    expect(resolveDefaultIrcAccountId(cfg)).toBe("ops-team");
+  });
+
+  it("falls back to default when configured defaultAccount is missing", () => {
+    const cfg = asConfig({
+      channels: {
+        irc: {
+          defaultAccount: "missing",
+          accounts: {
+            default: {},
+            work: {},
+          },
+        },
+      },
+    });
+
+    expect(resolveDefaultIrcAccountId(cfg)).toBe("default");
+  });
+
+  it("falls back to first sorted account when default is absent", () => {
+    const cfg = asConfig({
+      channels: {
+        irc: {
+          accounts: {
+            zzz: {},
+            aaa: {},
+          },
+        },
+      },
+    });
+
+    expect(resolveDefaultIrcAccountId(cfg)).toBe("aaa");
+  });
+});
+
+describe("resolveIrcAccount", () => {
+  it("matches normalized configured account ids", () => {
+    const account = resolveIrcAccount({
+      cfg: asConfig({
+        channels: {
+          irc: {
+            accounts: {
+              "Ops Team": {
+                host: "irc.example.com",
+                nick: "actagent",
+              },
+            },
+          },
+        },
+      }),
+      accountId: "ops-team",
+    });
+
+    expect(account.accountId).toBe("ops-team");
+    expect(account.host).toBe("irc.example.com");
+    expect(account.nick).toBe("actagent");
+    expect(account.configured).toBe(true);
+  });
+
+  it("parses delimited IRC_CHANNELS env values for the default account", () => {
+    vi.stubEnv("IRC_CHANNELS", "alpha, beta\ngamma; delta");
+
+    try {
+      const account = resolveIrcAccount({
+        cfg: asConfig({
+          channels: {
+            irc: {
+              host: "irc.example.com",
+              nick: "actagent",
+            },
+          },
+        }),
+      });
+
+      expect(account.config.channels).toEqual(["alpha", "beta", "gamma", "delta"]);
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  it.runIf(process.platform !== "win32")("rejects symlinked password files", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "actagent-irc-account-"));
+    const passwordFile = path.join(dir, "password.txt");
+    const passwordLink = path.join(dir, "password-link.txt");
+    fs.writeFileSync(passwordFile, "secret-pass\n", "utf8");
+    fs.symlinkSync(passwordFile, passwordLink);
+
+    const cfg = asConfig({
+      channels: {
+        irc: {
+          host: "irc.example.com",
+          nick: "actagent",
+          passwordFile: passwordLink,
+        },
+      },
+    });
+
+    expect(() => resolveIrcAccount({ cfg })).toThrow(/IRC password file.*must not be a symlink/);
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it.runIf(process.platform !== "win32")("rejects symlinked NickServ password files", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "actagent-irc-nickserv-"));
+    const passwordFile = path.join(dir, "nickserv-password.txt");
+    const passwordLink = path.join(dir, "nickserv-password-link.txt");
+    fs.writeFileSync(passwordFile, "nickserv-pass\n", "utf8");
+    fs.symlinkSync(passwordFile, passwordLink);
+
+    const cfg = asConfig({
+      channels: {
+        irc: {
+          host: "irc.example.com",
+          nick: "actagent",
+          nickserv: {
+            passwordFile: passwordLink,
+          },
+        },
+      },
+    });
+
+    expect(() => resolveIrcAccount({ cfg })).toThrow(
+      /IRC NickServ password file.*must not be a symlink/,
+    );
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("preserves shared NickServ config when an account overrides one NickServ field", () => {
+    const account = resolveIrcAccount({
+      cfg: asConfig({
+        channels: {
+          irc: {
+            host: "irc.example.com",
+            nick: "actagent",
+            nickserv: {
+              service: "NickServ",
+            },
+            accounts: {
+              work: {
+                nickserv: {
+                  registerEmail: "work@example.com",
+                },
+              },
+            },
+          },
+        },
+      }),
+      accountId: "work",
+    });
+
+    expect(account.config.nickserv).toEqual({
+      service: "NickServ",
+      registerEmail: "work@example.com",
+    });
+  });
+});

package/src/accounts.ts

@@ -0,0 +1,240 @@
+// Irc plugin module implements accounts behavior.
+import { createAccountListHelpers } from "actagent/plugin-sdk/account-helpers";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "actagent/plugin-sdk/account-id";
+import { resolveMergedAccountConfig } from "actagent/plugin-sdk/account-resolution";
+import {
+  parseOptionalDelimitedEntries,
+  tryReadSecretFileSync,
+} from "actagent/plugin-sdk/channel-core";
+import { parseStrictPositiveInteger } from "actagent/plugin-sdk/number-runtime";
+import { normalizeResolvedSecretInputString } from "actagent/plugin-sdk/secret-input";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "actagent/plugin-sdk/string-coerce-runtime";
+import type { CoreConfig, IrcAccountConfig, IrcNickServConfig } from "./types.js";
+
+const TRUTHY_ENV = new Set(["true", "1", "yes", "on"]);
+
+export type ResolvedIrcAccount = {
+  accountId: string;
+  enabled: boolean;
+  name?: string;
+  configured: boolean;
+  host: string;
+  port: number;
+  tls: boolean;
+  nick: string;
+  username: string;
+  realname: string;
+  password: string;
+  passwordSource: "env" | "passwordFile" | "config" | "none";
+  config: IrcAccountConfig;
+};
+
+function parseTruthy(value?: string): boolean {
+  if (!value) {
+    return false;
+  }
+  return TRUTHY_ENV.has(normalizeLowercaseStringOrEmpty(value));
+}
+
+function parseIntEnv(value?: string): number | undefined {
+  if (!value?.trim()) {
+    return undefined;
+  }
+  const parsed = parseStrictPositiveInteger(value);
+  if (parsed === undefined || parsed > 65535) {
+    return undefined;
+  }
+  return parsed;
+}
+
+const { listAccountIds: listIrcAccountIds, resolveDefaultAccountId: resolveDefaultIrcAccountId } =
+  createAccountListHelpers("irc", {
+    normalizeAccountId,
+    hasImplicitDefaultAccount: (cfg) =>
+      Boolean(
+        (cfg.channels?.irc?.host?.trim() || process.env.IRC_HOST?.trim()) &&
+        (cfg.channels?.irc?.nick?.trim() || process.env.IRC_NICK?.trim()),
+      ),
+  });
+export { listIrcAccountIds, resolveDefaultIrcAccountId };
+
+function mergeIrcAccountConfig(cfg: CoreConfig, accountId: string): IrcAccountConfig {
+  return resolveMergedAccountConfig<IrcAccountConfig>({
+    channelConfig: cfg.channels?.irc as IrcAccountConfig | undefined,
+    accounts: cfg.channels?.irc?.accounts as Record<string, Partial<IrcAccountConfig>> | undefined,
+    accountId,
+    omitKeys: ["defaultAccount"],
+    normalizeAccountId,
+    nestedObjectKeys: ["nickserv"],
+  });
+}
+
+function resolvePassword(accountId: string, merged: IrcAccountConfig) {
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    const envPassword = process.env.IRC_PASSWORD?.trim();
+    if (envPassword) {
+      return { password: envPassword, source: "env" as const };
+    }
+  }
+
+  if (merged.passwordFile?.trim()) {
+    const filePassword = tryReadSecretFileSync(merged.passwordFile, "IRC password file", {
+      rejectSymlink: true,
+    });
+    if (filePassword) {
+      return { password: filePassword, source: "passwordFile" as const };
+    }
+  }
+
+  const configPassword = normalizeResolvedSecretInputString({
+    value: merged.password,
+    path: `channels.irc.accounts.${accountId}.password`,
+  });
+  if (configPassword) {
+    return { password: configPassword, source: "config" as const };
+  }
+
+  return { password: "", source: "none" as const };
+}
+
+function resolveNickServConfig(accountId: string, nickserv?: IrcNickServConfig): IrcNickServConfig {
+  const base = nickserv ?? {};
+  const envPassword =
+    accountId === DEFAULT_ACCOUNT_ID ? process.env.IRC_NICKSERV_PASSWORD?.trim() : undefined;
+  const envRegisterEmail =
+    accountId === DEFAULT_ACCOUNT_ID ? process.env.IRC_NICKSERV_REGISTER_EMAIL?.trim() : undefined;
+
+  const passwordFile = base.passwordFile?.trim();
+  let resolvedPassword =
+    normalizeResolvedSecretInputString({
+      value: base.password,
+      path: `channels.irc.accounts.${accountId}.nickserv.password`,
+    }) ||
+    envPassword ||
+    "";
+  if (!resolvedPassword && passwordFile) {
+    resolvedPassword =
+      tryReadSecretFileSync(passwordFile, "IRC NickServ password file", {
+        rejectSymlink: true,
+      }) ?? "";
+  }
+
+  const merged: IrcNickServConfig = {
+    ...base,
+    service: normalizeOptionalString(base.service),
+    passwordFile: passwordFile || undefined,
+    password: resolvedPassword || undefined,
+    registerEmail: base.registerEmail?.trim() || envRegisterEmail || undefined,
+  };
+  return merged;
+}
+
+export function resolveIrcAccount(params: {
+  cfg: CoreConfig;
+  accountId?: string | null;
+}): ResolvedIrcAccount {
+  const hasExplicitAccountId = Boolean(params.accountId?.trim());
+  const baseEnabled = params.cfg.channels?.irc?.enabled !== false;
+
+  const resolve = (accountId: string) => {
+    const merged = mergeIrcAccountConfig(params.cfg, accountId);
+    const accountEnabled = merged.enabled !== false;
+    const enabled = baseEnabled && accountEnabled;
+
+    const tls =
+      typeof merged.tls === "boolean"
+        ? merged.tls
+        : accountId === DEFAULT_ACCOUNT_ID && process.env.IRC_TLS
+          ? parseTruthy(process.env.IRC_TLS)
+          : true;
+
+    const envPort =
+      accountId === DEFAULT_ACCOUNT_ID ? parseIntEnv(process.env.IRC_PORT) : undefined;
+    const port = merged.port ?? envPort ?? (tls ? 6697 : 6667);
+    const envChannels =
+      accountId === DEFAULT_ACCOUNT_ID
+        ? parseOptionalDelimitedEntries(process.env.IRC_CHANNELS)
+        : undefined;
+
+    const host = (
+      merged.host?.trim() ||
+      (accountId === DEFAULT_ACCOUNT_ID ? process.env.IRC_HOST?.trim() : "") ||
+      ""
+    ).trim();
+    const nick = (
+      merged.nick?.trim() ||
+      (accountId === DEFAULT_ACCOUNT_ID ? process.env.IRC_NICK?.trim() : "") ||
+      ""
+    ).trim();
+    const username = (
+      merged.username?.trim() ||
+      (accountId === DEFAULT_ACCOUNT_ID ? process.env.IRC_USERNAME?.trim() : "") ||
+      nick ||
+      "actagent"
+    ).trim();
+    const realname = (
+      merged.realname?.trim() ||
+      (accountId === DEFAULT_ACCOUNT_ID ? process.env.IRC_REALNAME?.trim() : "") ||
+      "ACTAgent"
+    ).trim();
+
+    const passwordResolution = resolvePassword(accountId, merged);
+    const nickserv = resolveNickServConfig(accountId, merged.nickserv);
+
+    const config: IrcAccountConfig = {
+      ...merged,
+      channels: merged.channels ?? envChannels,
+      tls,
+      port,
+      host,
+      nick,
+      username,
+      realname,
+      nickserv,
+    };
+
+    return {
+      accountId,
+      enabled,
+      name: normalizeOptionalString(merged.name),
+      configured: Boolean(host && nick),
+      host,
+      port,
+      tls,
+      nick,
+      username,
+      realname,
+      password: passwordResolution.password,
+      passwordSource: passwordResolution.source,
+      config,
+    } satisfies ResolvedIrcAccount;
+  };
+
+  const normalized = normalizeAccountId(params.accountId);
+  const primary = resolve(normalized);
+  if (hasExplicitAccountId) {
+    return primary;
+  }
+  if (primary.configured) {
+    return primary;
+  }
+
+  const fallbackId = resolveDefaultIrcAccountId(params.cfg);
+  if (fallbackId === primary.accountId) {
+    return primary;
+  }
+  const fallback = resolve(fallbackId);
+  if (!fallback.configured) {
+    return primary;
+  }
+  return fallback;
+}
+
+export function listEnabledIrcAccounts(cfg: CoreConfig): ResolvedIrcAccount[] {
+  return listIrcAccountIds(cfg)
+    .map((accountId) => resolveIrcAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

package/src/channel-api.ts

@@ -0,0 +1,7 @@
+// Irc API module exposes the plugin public contract.
+export { createAccountStatusSink } from "actagent/plugin-sdk/channel-outbound";
+export { DEFAULT_ACCOUNT_ID } from "actagent/plugin-sdk/account-id";
+export type { ChannelPlugin } from "actagent/plugin-sdk/channel-core";
+export { PAIRING_APPROVED_MESSAGE } from "actagent/plugin-sdk/channel-status";
+export { buildBaseChannelStatusSummary } from "actagent/plugin-sdk/status-helpers";
+export { chunkTextForOutbound } from "actagent/plugin-sdk/text-chunking";

package/src/channel-runtime.ts

@@ -0,0 +1,4 @@
+// Runtime-only IRC helpers for lazy chat plugin hooks.
+// Keeping this boundary separate keeps bundled entry loads off monitor/send.
+export { monitorIrcProvider } from "./monitor.js";
+export { sendMessageIrc } from "./send.js";