@actagent/irc 2026.6.2

package/src/runtime-api.ts

@@ -0,0 +1,42 @@
+// Private runtime barrel for the bundled IRC extension.
+// Keep this barrel thin and generic-only.
+
+export type { BaseProbeResult } from "actagent/plugin-sdk/channel-contract";
+export type { ChannelPlugin } from "actagent/plugin-sdk/channel-core";
+export type { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+export type { PluginRuntime } from "actagent/plugin-sdk/runtime-store";
+export type { RuntimeEnv } from "actagent/plugin-sdk/runtime";
+export type {
+  BlockStreamingCoalesceConfig,
+  DmConfig,
+  DmPolicy,
+  GroupPolicy,
+  GroupToolPolicyBySenderConfig,
+  GroupToolPolicyConfig,
+  MarkdownConfig,
+} from "actagent/plugin-sdk/config-contracts";
+export type { OutboundReplyPayload } from "actagent/plugin-sdk/reply-payload";
+export { DEFAULT_ACCOUNT_ID } from "actagent/plugin-sdk/account-id";
+export { buildChannelConfigSchema } from "actagent/plugin-sdk/channel-config-primitives";
+export {
+  PAIRING_APPROVED_MESSAGE,
+  buildBaseChannelStatusSummary,
+} from "actagent/plugin-sdk/channel-status";
+export { createChannelPairingController } from "actagent/plugin-sdk/channel-pairing";
+export { createAccountStatusSink } from "actagent/plugin-sdk/channel-outbound";
+export { resolveControlCommandGate } from "actagent/plugin-sdk/command-auth-native";
+export { createChannelMessageReplyPipeline } from "actagent/plugin-sdk/channel-outbound";
+export { chunkTextForOutbound } from "actagent/plugin-sdk/text-chunking";
+export {
+  deliverFormattedTextWithAttachments,
+  formatTextWithAttachmentLinks,
+  resolveOutboundMediaUrls,
+} from "actagent/plugin-sdk/reply-payload";
+export {
+  GROUP_POLICY_BLOCKED_LABEL,
+  resolveAllowlistProviderRuntimeGroupPolicy,
+  resolveDefaultGroupPolicy,
+  warnMissingProviderGroupPolicyFallbackOnce,
+} from "actagent/plugin-sdk/runtime-group-policy";
+export { isDangerousNameMatchingEnabled } from "actagent/plugin-sdk/dangerous-name-runtime";
+export { logInboundDrop } from "actagent/plugin-sdk/channel-inbound";

package/src/runtime.ts

@@ -0,0 +1,16 @@
+// Irc plugin module implements runtime behavior.
+import { createPluginRuntimeStore } from "actagent/plugin-sdk/runtime-store";
+import type { PluginRuntime } from "./runtime-api.js";
+
+const {
+  setRuntime: setIrcRuntime,
+  clearRuntime: clearStoredIrcRuntime,
+  getRuntime: getIrcRuntime,
+} = createPluginRuntimeStore<PluginRuntime>({
+  pluginId: "irc",
+  errorMessage: "IRC runtime not initialized",
+});
+export { getIrcRuntime, setIrcRuntime };
+export function clearIrcRuntime() {
+  clearStoredIrcRuntime();
+}

package/src/secret-contract.ts

@@ -0,0 +1,104 @@
+// Irc plugin module implements secret contract behavior.
+import {
+  collectNestedChannelFieldAssignments,
+  collectSimpleChannelFieldAssignments,
+  getChannelSurface,
+  isBaseFieldActiveForChannelSurface,
+  isEnabledFlag,
+  isRecord,
+  type ResolverContext,
+  type SecretDefaults,
+} from "actagent/plugin-sdk/channel-secret-basic-runtime";
+
+export const secretTargetRegistryEntries: import("actagent/plugin-sdk/channel-secret-basic-runtime").SecretTargetRegistryEntry[] =
+  [
+    {
+      id: "channels.irc.accounts.*.nickserv.password",
+      targetType: "channels.irc.accounts.*.nickserv.password",
+      configFile: "actagent.json",
+      pathPattern: "channels.irc.accounts.*.nickserv.password",
+      secretShape: "secret_input",
+      expectedResolvedValue: "string",
+      includeInPlan: true,
+      includeInConfigure: true,
+      includeInAudit: true,
+    },
+    {
+      id: "channels.irc.accounts.*.password",
+      targetType: "channels.irc.accounts.*.password",
+      configFile: "actagent.json",
+      pathPattern: "channels.irc.accounts.*.password",
+      secretShape: "secret_input",
+      expectedResolvedValue: "string",
+      includeInPlan: true,
+      includeInConfigure: true,
+      includeInAudit: true,
+    },
+    {
+      id: "channels.irc.nickserv.password",
+      targetType: "channels.irc.nickserv.password",
+      configFile: "actagent.json",
+      pathPattern: "channels.irc.nickserv.password",
+      secretShape: "secret_input",
+      expectedResolvedValue: "string",
+      includeInPlan: true,
+      includeInConfigure: true,
+      includeInAudit: true,
+    },
+    {
+      id: "channels.irc.password",
+      targetType: "channels.irc.password",
+      configFile: "actagent.json",
+      pathPattern: "channels.irc.password",
+      secretShape: "secret_input",
+      expectedResolvedValue: "string",
+      includeInPlan: true,
+      includeInConfigure: true,
+      includeInAudit: true,
+    },
+  ];
+
+export function collectRuntimeConfigAssignments(params: {
+  config: { channels?: Record<string, unknown> };
+  defaults?: SecretDefaults;
+  context: ResolverContext;
+}): void {
+  const resolved = getChannelSurface(params.config, "irc");
+  if (!resolved) {
+    return;
+  }
+  const { channel: irc, surface } = resolved;
+  collectSimpleChannelFieldAssignments({
+    channelKey: "irc",
+    field: "password",
+    channel: irc,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topInactiveReason: "no enabled account inherits this top-level IRC password.",
+    accountInactiveReason: "IRC account is disabled.",
+  });
+  collectNestedChannelFieldAssignments({
+    channelKey: "irc",
+    nestedKey: "nickserv",
+    field: "password",
+    channel: irc,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topLevelActive:
+      isBaseFieldActiveForChannelSurface(surface, "nickserv") &&
+      isRecord(irc.nickserv) &&
+      isEnabledFlag(irc.nickserv),
+    topInactiveReason:
+      "no enabled account inherits this top-level IRC nickserv config or NickServ is disabled.",
+    accountActive: ({ account, enabled }) =>
+      enabled && isRecord(account.nickserv) && isEnabledFlag(account.nickserv),
+    accountInactiveReason: "IRC account is disabled or NickServ is disabled for this account.",
+  });
+}
+
+export const channelSecrets = {
+  secretTargetRegistryEntries,
+  collectRuntimeConfigAssignments,
+};

package/src/send.test.ts

@@ -0,0 +1,327 @@
+// Irc tests cover send plugin behavior.
+import { verifyChannelMessageAdapterCapabilityProofs } from "actagent/plugin-sdk/channel-outbound";
+import { createSendCfgThreadingRuntime } from "actagent/plugin-sdk/channel-test-helpers";
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { IrcClient } from "./client.js";
+import { clearIrcRuntime, setIrcRuntime } from "./runtime.js";
+import type { CoreConfig } from "./types.js";
+
+const hoisted = vi.hoisted(() => {
+  const loadConfig = vi.fn();
+  const resolveMarkdownTableMode = vi.fn(() => "preserve");
+  const convertMarkdownTables = vi.fn((text: string) => text);
+  const record = vi.fn();
+  return {
+    loadConfig,
+    resolveMarkdownTableMode,
+    convertMarkdownTables,
+    record,
+    normalizeIrcMessagingTarget: vi.fn((value: string) => value.trim()),
+    connectIrcClient: vi.fn(),
+    buildIrcConnectOptions: vi.fn(() => ({})),
+  };
+});
+
+vi.mock("./normalize.js", () => ({
+  normalizeIrcMessagingTarget: hoisted.normalizeIrcMessagingTarget,
+}));
+
+vi.mock("./client.js", () => ({
+  connectIrcClient: hoisted.connectIrcClient,
+}));
+
+vi.mock("./connect-options.js", () => ({
+  buildIrcConnectOptions: hoisted.buildIrcConnectOptions,
+}));
+
+vi.mock("./protocol.js", async () => {
+  const actual = await vi.importActual<typeof import("./protocol.js")>("./protocol.js");
+  return {
+    ...actual,
+    makeIrcMessageId: () => "irc-msg-1",
+  };
+});
+
+vi.mock("actagent/plugin-sdk/plugin-config-runtime", async () => {
+  const original = (await vi.importActual("actagent/plugin-sdk/plugin-config-runtime")) as Record<
+    string,
+    unknown
+  >;
+  return {
+    ...original,
+    resolveMarkdownTableMode: hoisted.resolveMarkdownTableMode,
+  };
+});
+
+vi.mock("actagent/plugin-sdk/text-chunking", async () => {
+  const original = (await vi.importActual("actagent/plugin-sdk/text-chunking")) as Record<
+    string,
+    unknown
+  >;
+  return {
+    ...original,
+    convertMarkdownTables: hoisted.convertMarkdownTables,
+  };
+});
+
+import { ircMessageAdapter } from "./message-adapter.js";
+import { sendMessageIrc } from "./send.js";
+
+function resetHoistedMocks() {
+  hoisted.loadConfig.mockReset();
+  hoisted.resolveMarkdownTableMode.mockReset().mockReturnValue("preserve");
+  hoisted.convertMarkdownTables.mockReset().mockImplementation((text: string) => text);
+  hoisted.record.mockReset();
+  hoisted.normalizeIrcMessagingTarget
+    .mockReset()
+    .mockImplementation((value: string) => value.trim());
+  hoisted.connectIrcClient.mockReset();
+  hoisted.buildIrcConnectOptions.mockReset().mockReturnValue({});
+}
+
+afterAll(() => {
+  vi.doUnmock("./normalize.js");
+  vi.doUnmock("./client.js");
+  vi.doUnmock("./connect-options.js");
+  vi.doUnmock("./protocol.js");
+  vi.doUnmock("actagent/plugin-sdk/plugin-config-runtime");
+  vi.doUnmock("actagent/plugin-sdk/text-chunking");
+  vi.resetModules();
+});
+
+describe("sendMessageIrc cfg threading", () => {
+  beforeEach(() => {
+    resetHoistedMocks();
+    setIrcRuntime(createSendCfgThreadingRuntime(hoisted) as never);
+  });
+
+  afterEach(() => {
+    clearIrcRuntime();
+  });
+
+  it("uses explicitly provided cfg without loading runtime config", async () => {
+    const providedCfg = {
+      channels: {
+        irc: {
+          host: "irc.example.com",
+          nick: "actagent",
+          accounts: {
+            work: {
+              host: "irc.example.com",
+              nick: "workbot",
+            },
+          },
+        },
+      },
+    } as unknown as CoreConfig;
+    const client = {
+      isReady: vi.fn(() => true),
+      sendPrivmsg: vi.fn(),
+    } as unknown as IrcClient;
+
+    const result = await sendMessageIrc("#room", "hello", {
+      cfg: providedCfg,
+      client,
+      accountId: "work",
+    });
+
+    expect(hoisted.loadConfig).not.toHaveBeenCalled();
+    expect(client.sendPrivmsg).toHaveBeenCalledWith("#room", "hello");
+    expect(hoisted.record).toHaveBeenCalledWith({
+      channel: "irc",
+      accountId: "work",
+      direction: "outbound",
+    });
+    expect(result.target).toBe("#room");
+    expect(result.messageId).toBeTypeOf("string");
+    expect(result.messageId.length).toBeGreaterThan(0);
+    expect(result.receipt.sentAt).toBeTypeOf("number");
+    expect(result.receipt.sentAt).toBeGreaterThan(0);
+    expect({ ...result.receipt, sentAt: 123 }).toEqual({
+      primaryPlatformMessageId: "irc-msg-1",
+      platformMessageIds: ["irc-msg-1"],
+      parts: [
+        {
+          platformMessageId: "irc-msg-1",
+          kind: "text",
+          index: 0,
+          raw: {
+            channel: "irc",
+            conversationId: "#room",
+            messageId: "irc-msg-1",
+          },
+        },
+      ],
+      sentAt: 123,
+      raw: [
+        {
+          channel: "irc",
+          conversationId: "#room",
+          messageId: "irc-msg-1",
+        },
+      ],
+    });
+  });
+
+  it("fails hard when cfg is omitted", async () => {
+    const client = {
+      isReady: vi.fn(() => true),
+      sendPrivmsg: vi.fn(),
+    } as unknown as IrcClient;
+
+    await expect(sendMessageIrc("#ops", "ping", { client } as never)).rejects.toThrow(
+      "IRC send requires a resolved runtime config",
+    );
+
+    expect(hoisted.loadConfig).not.toHaveBeenCalled();
+    expect(client.sendPrivmsg).not.toHaveBeenCalled();
+    expect(hoisted.record).not.toHaveBeenCalled();
+  });
+
+  it("sends with provided cfg even when the runtime store is not initialized", async () => {
+    const providedCfg = {
+      channels: {
+        irc: {
+          host: "irc.example.com",
+          nick: "actagent",
+        },
+      },
+    } as unknown as CoreConfig;
+    const client = {
+      isReady: vi.fn(() => true),
+      sendPrivmsg: vi.fn(),
+    } as unknown as IrcClient;
+    hoisted.record.mockImplementation(() => {
+      throw new Error("IRC runtime not initialized");
+    });
+
+    const result = await sendMessageIrc("#room", "hello", {
+      cfg: providedCfg,
+      client,
+    });
+
+    expect(hoisted.loadConfig).not.toHaveBeenCalled();
+    expect(client.sendPrivmsg).toHaveBeenCalledWith("#room", "hello");
+    expect(result.target).toBe("#room");
+    expect(result.messageId).toBeTypeOf("string");
+    expect(result.messageId.length).toBeGreaterThan(0);
+  });
+
+  it("preserves reply ids in receipts", async () => {
+    const providedCfg = {
+      channels: {
+        irc: {
+          host: "irc.example.com",
+          nick: "actagent",
+        },
+      },
+    } as unknown as CoreConfig;
+    const client = {
+      isReady: vi.fn(() => true),
+      sendPrivmsg: vi.fn(),
+    } as unknown as IrcClient;
+
+    const result = await sendMessageIrc("#room", "hello", {
+      cfg: providedCfg,
+      client,
+      replyTo: "irc-parent-1",
+    });
+
+    expect(client.sendPrivmsg).toHaveBeenCalledWith("#room", "hello\n\n[reply:irc-parent-1]");
+    expect(result.receipt.sentAt).toBeTypeOf("number");
+    expect(result.receipt.sentAt).toBeGreaterThan(0);
+    expect({ ...result.receipt, sentAt: 123 }).toEqual({
+      primaryPlatformMessageId: "irc-msg-1",
+      platformMessageIds: ["irc-msg-1"],
+      replyToId: "irc-parent-1",
+      parts: [
+        {
+          platformMessageId: "irc-msg-1",
+          kind: "text",
+          index: 0,
+          replyToId: "irc-parent-1",
+          raw: {
+            channel: "irc",
+            conversationId: "#room",
+            messageId: "irc-msg-1",
+          },
+        },
+      ],
+      sentAt: 123,
+      raw: [
+        {
+          channel: "irc",
+          conversationId: "#room",
+          messageId: "irc-msg-1",
+        },
+      ],
+    });
+  });
+
+  it("declares message adapter durable text, media, and reply with receipt proofs", async () => {
+    const providedCfg = {
+      channels: {
+        irc: {
+          host: "irc.example.com",
+          nick: "actagent",
+        },
+      },
+    } as unknown as CoreConfig;
+    const client = {
+      isReady: vi.fn(() => true),
+      join: vi.fn(),
+      sendPrivmsg: vi.fn(),
+      quit: vi.fn(),
+    } as unknown as IrcClient & {
+      join: ReturnType<typeof vi.fn>;
+      quit: ReturnType<typeof vi.fn>;
+    };
+    hoisted.connectIrcClient.mockResolvedValue(client);
+
+    const proofResults = await verifyChannelMessageAdapterCapabilityProofs({
+      adapterName: "irc",
+      adapter: ircMessageAdapter,
+      proofs: {
+        text: async () => {
+          const result = await ircMessageAdapter.send?.text?.({
+            cfg: providedCfg,
+            to: "#room",
+            text: "hello",
+          });
+          expect(result?.receipt.platformMessageIds).toEqual(["irc-msg-1"]);
+          expect(client.join).toHaveBeenCalledWith("#room");
+          expect(client.sendPrivmsg).toHaveBeenCalledWith("#room", "hello");
+        },
+        media: async () => {
+          const result = await ircMessageAdapter.send?.media?.({
+            cfg: providedCfg,
+            to: "#room",
+            text: "image",
+            mediaUrl: "https://example.com/image.png",
+          });
+          expect(result?.receipt.platformMessageIds).toEqual(["irc-msg-1"]);
+          expect(client.join).toHaveBeenCalledWith("#room");
+          expect(client.sendPrivmsg).toHaveBeenCalledWith(
+            "#room",
+            "image\n\nAttachment: https://example.com/image.png",
+          );
+        },
+        replyTo: async () => {
+          const result = await ircMessageAdapter.send?.text?.({
+            cfg: providedCfg,
+            to: "#room",
+            text: "threaded",
+            replyToId: "parent-1",
+          });
+          expect(result?.receipt.replyToId).toBe("parent-1");
+          expect(client.join).toHaveBeenCalledWith("#room");
+          expect(client.sendPrivmsg).toHaveBeenCalledWith("#room", "threaded\n\n[reply:parent-1]");
+        },
+      },
+    });
+
+    expect(proofResults.find((result) => result.capability === "text")?.status).toBe("verified");
+    expect(proofResults.find((result) => result.capability === "media")?.status).toBe("verified");
+    expect(proofResults.find((result) => result.capability === "replyTo")?.status).toBe("verified");
+  });
+});

package/src/send.ts

@@ -0,0 +1,122 @@
+// Irc plugin module implements send behavior.
+import {
+  createMessageReceiptFromOutboundResults,
+  type MessageReceipt,
+} from "actagent/plugin-sdk/channel-outbound";
+import { resolveMarkdownTableMode } from "actagent/plugin-sdk/markdown-table-runtime";
+import { requireRuntimeConfig } from "actagent/plugin-sdk/plugin-config-runtime";
+import { convertMarkdownTables } from "actagent/plugin-sdk/text-chunking";
+import { resolveIrcAccount } from "./accounts.js";
+import type { IrcClient } from "./client.js";
+import { connectIrcClient } from "./client.js";
+import { buildIrcConnectOptions } from "./connect-options.js";
+import { normalizeIrcMessagingTarget } from "./normalize.js";
+import { makeIrcMessageId } from "./protocol.js";
+import { getIrcRuntime } from "./runtime.js";
+import type { CoreConfig } from "./types.js";
+
+type SendIrcOptions = {
+  cfg: CoreConfig;
+  accountId?: string;
+  replyTo?: string;
+  target?: string;
+  client?: IrcClient;
+};
+
+type SendIrcResult = {
+  messageId: string;
+  target: string;
+  receipt: MessageReceipt;
+};
+
+function recordIrcOutboundActivity(accountId: string): void {
+  try {
+    getIrcRuntime().channel.activity.record({
+      channel: "irc",
+      accountId,
+      direction: "outbound",
+    });
+  } catch (error) {
+    if (!(error instanceof Error) || error.message !== "IRC runtime not initialized") {
+      throw error;
+    }
+  }
+}
+
+function resolveTarget(to: string, opts?: SendIrcOptions): string {
+  const fromArg = normalizeIrcMessagingTarget(to);
+  if (fromArg) {
+    return fromArg;
+  }
+  const fromOpt = normalizeIrcMessagingTarget(opts?.target ?? "");
+  if (fromOpt) {
+    return fromOpt;
+  }
+  throw new Error(`Invalid IRC target: ${to}`);
+}
+
+export async function sendMessageIrc(
+  to: string,
+  text: string,
+  opts: SendIrcOptions,
+): Promise<SendIrcResult> {
+  const cfg = requireRuntimeConfig(opts.cfg, "IRC send") as CoreConfig;
+  const account = resolveIrcAccount({
+    cfg,
+    accountId: opts.accountId,
+  });
+
+  if (!account.configured) {
+    throw new Error(
+      `IRC is not configured for account "${account.accountId}" (need host and nick in channels.irc).`,
+    );
+  }
+
+  const target = resolveTarget(to, opts);
+  const tableMode = resolveMarkdownTableMode({
+    cfg,
+    channel: "irc",
+    accountId: account.accountId,
+  });
+  const prepared = convertMarkdownTables(text.trim(), tableMode);
+  const payload = opts.replyTo ? `${prepared}\n\n[reply:${opts.replyTo}]` : prepared;
+
+  if (!payload.trim()) {
+    throw new Error("Message must be non-empty for IRC sends");
+  }
+
+  const client = opts.client;
+  if (client?.isReady()) {
+    client.sendPrivmsg(target, payload);
+  } else {
+    const transient = await connectIrcClient(
+      buildIrcConnectOptions(account, {
+        connectTimeoutMs: 12000,
+      }),
+    );
+    if (target.startsWith("#") || target.startsWith("&")) {
+      transient.join(target);
+    }
+    transient.sendPrivmsg(target, payload);
+    transient.quit("sent");
+  }
+
+  recordIrcOutboundActivity(account.accountId);
+
+  const messageId = makeIrcMessageId();
+  return {
+    messageId,
+    target,
+    receipt: createMessageReceiptFromOutboundResults({
+      results: [
+        {
+          channel: "irc",
+          messageId,
+          conversationId: target,
+        },
+      ],
+      kind: "text",
+      ...(opts.replyTo ? { replyToId: opts.replyTo } : {}),
+    }),
+  };
+}