@openclaw/twitch 2026.2.21 → 2026.5.2-beta.1

package/src/access-control.test.ts

@@ -17,16 +17,79 @@ describe("checkTwitchAccessControl", () => {
     channel: "testchannel",
   };
 
-  describe("when no restrictions are configured", () => {
-    it("allows messages that mention the bot (default requireMention)", () => {
-      const message: TwitchChatMessage = {
+  function runAccessCheck(params: {
+    account?: Partial<TwitchAccountConfig>;
+    message?: Partial<TwitchChatMessage>;
+  }) {
+    return checkTwitchAccessControl({
+      message: {
         ...mockMessage,
+        ...params.message,
+      },
+      account: {
+        ...mockAccount,
+        ...params.account,
+      },
+      botUsername: "testbot",
+    });
+  }
+
+  function expectSingleRoleAllowed(params: {
+    role: NonNullable<TwitchAccountConfig["allowedRoles"]>[number];
+    message: Partial<TwitchChatMessage>;
+  }) {
+    const result = runAccessCheck({
+      account: { allowedRoles: [params.role] },
+      message: {
         message: "@testbot hello",
-      };
-      const result = checkTwitchAccessControl({
-        message,
-        account: mockAccount,
-        botUsername: "testbot",
+        ...params.message,
+      },
+    });
+    expect(result.allowed).toBe(true);
+    return result;
+  }
+
+  function expectAllowedAccessCheck(params: {
+    account?: Partial<TwitchAccountConfig>;
+    message?: Partial<TwitchChatMessage>;
+  }) {
+    const result = runAccessCheck({
+      account: params.account,
+      message: {
+        message: "@testbot hello",
+        ...params.message,
+      },
+    });
+    expect(result.allowed).toBe(true);
+    return result;
+  }
+
+  function expectAllowFromBlocked(params: {
+    allowFrom: string[];
+    allowedRoles?: NonNullable<TwitchAccountConfig["allowedRoles"]>;
+    message?: Partial<TwitchChatMessage>;
+    reason: string;
+  }) {
+    const result = runAccessCheck({
+      account: {
+        allowFrom: params.allowFrom,
+        allowedRoles: params.allowedRoles,
+      },
+      message: {
+        message: "@testbot hello",
+        ...params.message,
+      },
+    });
+    expect(result.allowed).toBe(false);
+    expect(result.reason).toContain(params.reason);
+  }
+
+  describe("when no restrictions are configured", () => {
+    it("allows messages that mention the bot (default requireMention)", () => {
+      const result = runAccessCheck({
+        message: {
+          message: "@testbot hello",
+        },
       });
       expect(result.allowed).toBe(true);
     });
@@ -34,30 +97,20 @@ describe("checkTwitchAccessControl", () => {
 
   describe("requireMention default", () => {
     it("defaults to true when undefined", () => {
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "hello bot",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account: mockAccount,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        message: {
+          message: "hello bot",
+        },
       });
       expect(result.allowed).toBe(false);
       expect(result.reason).toContain("does not mention the bot");
     });
 
     it("allows mention when requireMention is undefined", () => {
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account: mockAccount,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        message: {
+          message: "@testbot hello",
+        },
       });
       expect(result.allowed).toBe(true);
     });
@@ -65,52 +118,25 @@ describe("checkTwitchAccessControl", () => {
 
   describe("requireMention", () => {
     it("allows messages that mention the bot", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        requireMention: true,
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        account: { requireMention: true },
+        message: { message: "@testbot hello" },
       });
       expect(result.allowed).toBe(true);
     });
 
     it("blocks messages that don't mention the bot", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        requireMention: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message: mockMessage,
-        account,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        account: { requireMention: true },
       });
       expect(result.allowed).toBe(false);
       expect(result.reason).toContain("does not mention the bot");
     });
 
     it("is case-insensitive for bot username", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        requireMention: true,
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@TestBot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        account: { requireMention: true },
+        message: { message: "@TestBot hello" },
       });
       expect(result.allowed).toBe(true);
     });
@@ -118,62 +144,35 @@ describe("checkTwitchAccessControl", () => {
 
   describe("allowFrom allowlist", () => {
     it("allows users in the allowlist", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowFrom: ["123456", "789012"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = expectAllowedAccessCheck({
+        account: {
+          allowFrom: ["123456", "789012"],
+        },
       });
-      expect(result.allowed).toBe(true);
       expect(result.matchKey).toBe("123456");
       expect(result.matchSource).toBe("allowlist");
     });
 
     it("blocks users not in allowlist when allowFrom is set", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
+      expectAllowFromBlocked({
         allowFrom: ["789012"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
+        reason: "allowFrom",
+      });
+    });
 
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+    it("blocks everyone when allowFrom is explicitly empty", () => {
+      expectAllowFromBlocked({
+        allowFrom: [],
+        reason: "allowFrom",
       });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("allowFrom");
     });
 
     it("blocks messages without userId", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
+      expectAllowFromBlocked({
         allowFrom: ["123456"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        userId: undefined,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+        message: { userId: undefined },
+        reason: "user ID not available",
       });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("user ID not available");
     });
 
     it("bypasses role checks when user is in allowlist", () => {
@@ -197,68 +196,30 @@ describe("checkTwitchAccessControl", () => {
     });
 
     it("blocks user with role when not in allowlist", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
+      expectAllowFromBlocked({
         allowFrom: ["789012"],
         allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        userId: "123456",
-        isMod: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+        message: { userId: "123456", isMod: true },
+        reason: "allowFrom",
       });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("allowFrom");
     });
 
     it("blocks user not in allowlist even when roles configured", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
+      expectAllowFromBlocked({
         allowFrom: ["789012"],
         allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        userId: "123456",
-        isMod: false,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+        message: { userId: "123456", isMod: false },
+        reason: "allowFrom",
       });
-      expect(result.allowed).toBe(false);
-      expect(result.reason).toContain("allowFrom");
     });
   });
 
   describe("allowedRoles", () => {
     it("allows users with matching role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isMod: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = expectSingleRoleAllowed({
+        role: "moderator",
+        message: { isMod: true },
       });
-      expect(result.allowed).toBe(true);
       expect(result.matchSource).toBe("role");
     });
 
@@ -304,98 +265,40 @@ describe("checkTwitchAccessControl", () => {
     });
 
     it("allows all users when role is 'all'", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["all"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = expectAllowedAccessCheck({
+        account: {
+          allowedRoles: ["all"],
+        },
       });
-      expect(result.allowed).toBe(true);
       expect(result.matchKey).toBe("all");
     });
 
     it("handles moderator role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["moderator"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isMod: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      expectSingleRoleAllowed({
+        role: "moderator",
+        message: { isMod: true },
       });
-      expect(result.allowed).toBe(true);
     });
 
     it("handles subscriber role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["subscriber"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isSub: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      expectSingleRoleAllowed({
+        role: "subscriber",
+        message: { isSub: true },
       });
-      expect(result.allowed).toBe(true);
     });
 
     it("handles owner role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["owner"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isOwner: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      expectSingleRoleAllowed({
+        role: "owner",
+        message: { isOwner: true },
       });
-      expect(result.allowed).toBe(true);
     });
 
     it("handles vip role", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowedRoles: ["vip"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isVip: true,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      expectSingleRoleAllowed({
+        role: "vip",
+        message: { isVip: true },
       });
-      expect(result.allowed).toBe(true);
     });
   });
 
@@ -421,21 +324,15 @@ describe("checkTwitchAccessControl", () => {
     });
 
     it("checks allowlist before allowedRoles", () => {
-      const account: TwitchAccountConfig = {
-        ...mockAccount,
-        allowFrom: ["123456"],
-        allowedRoles: ["owner"],
-      };
-      const message: TwitchChatMessage = {
-        ...mockMessage,
-        message: "@testbot hello",
-        isOwner: false,
-      };
-
-      const result = checkTwitchAccessControl({
-        message,
-        account,
-        botUsername: "testbot",
+      const result = runAccessCheck({
+        account: {
+          allowFrom: ["123456"],
+          allowedRoles: ["owner"],
+        },
+        message: {
+          message: "@testbot hello",
+          isOwner: false,
+        },
       });
       expect(result.allowed).toBe(true);
       expect(result.matchSource).toBe("allowlist");

package/src/access-control.ts

@@ -1,9 +1,10 @@
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
 import type { TwitchAccountConfig, TwitchChatMessage } from "./types.js";
 
 /**
  * Result of checking access control for a Twitch message
  */
-export type TwitchAccessControlResult = {
+type TwitchAccessControlResult = {
   allowed: boolean;
   reason?: string;
   matchKey?: string;
@@ -40,7 +41,7 @@ export function checkTwitchAccessControl(params: {
 
   if (account.requireMention ?? true) {
     const mentions = extractMentions(message.message);
-    if (!mentions.includes(botUsername.toLowerCase())) {
+    if (!mentions.includes(normalizeLowercaseStringOrEmpty(botUsername))) {
       return {
         allowed: false,
         reason: "message does not mention the bot (requireMention is enabled)",
@@ -48,8 +49,14 @@ export function checkTwitchAccessControl(params: {
     }
   }
 
-  if (account.allowFrom && account.allowFrom.length > 0) {
+  if (account.allowFrom !== undefined) {
     const allowFrom = account.allowFrom;
+    if (allowFrom.length === 0) {
+      return {
+        allowed: false,
+        reason: "sender is not in allowFrom allowlist",
+      };
+    }
     const senderId = message.userId;
 
     if (!senderId) {
@@ -158,7 +165,7 @@ export function extractMentions(message: string): string[] {
   while ((match = mentionRegex.exec(message)) !== null) {
     const username = match[1];
     if (username) {
-      mentions.push(username.toLowerCase());
+      mentions.push(normalizeLowercaseStringOrEmpty(username));
     }
   }
 

package/src/actions.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { twitchMessageActions } from "./actions.js";
+import type { ResolvedTwitchAccountContext } from "./config.js";
+import { resolveTwitchAccountContext } from "./config.js";
+import { twitchOutbound } from "./outbound.js";
+
+vi.mock("./config.js", () => ({
+  DEFAULT_ACCOUNT_ID: "default",
+  resolveTwitchAccountContext: vi.fn(),
+}));
+
+vi.mock("./outbound.js", () => ({
+  twitchOutbound: {
+    sendText: vi.fn(),
+  },
+}));
+
+function createSecondaryAccountContext(accountId = "secondary"): ResolvedTwitchAccountContext {
+  return {
+    accountId,
+    account: {
+      channel: "secondary-channel",
+      username: "secondary",
+      accessToken: "oauth:secondary-token",
+      clientId: "secondary-client",
+      enabled: true,
+    },
+    tokenResolution: { source: "config", token: "oauth:secondary-token" },
+    configured: true,
+    availableAccountIds: ["default", "secondary"],
+  };
+}
+
+describe("twitchMessageActions", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("uses configured defaultAccount when action accountId is omitted", async () => {
+    vi.mocked(resolveTwitchAccountContext)
+      .mockImplementationOnce(() => createSecondaryAccountContext())
+      .mockImplementation((_cfg, accountId) =>
+        createSecondaryAccountContext(accountId?.trim() || "secondary"),
+      );
+    const sendText = twitchOutbound.sendText;
+    if (!sendText) {
+      throw new Error("twitchOutbound.sendText is unavailable");
+    }
+    vi.mocked(sendText).mockResolvedValue({
+      channel: "twitch",
+      messageId: "msg-1",
+      timestamp: 1,
+    });
+
+    await twitchMessageActions.handleAction!({
+      action: "send",
+      params: { message: "Hello!" },
+      cfg: {
+        channels: {
+          twitch: {
+            defaultAccount: "secondary",
+          },
+        },
+      },
+    } as never);
+
+    expect(twitchOutbound.sendText).toHaveBeenCalledWith(
+      expect.objectContaining({
+        accountId: "secondary",
+        to: "secondary-channel",
+      }),
+    );
+  });
+});

package/src/actions.ts

@@ -4,7 +4,8 @@
  * Handles tool-based actions for Twitch, such as sending messages.
  */
 
-import { DEFAULT_ACCOUNT_ID, getAccountConfig } from "./config.js";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { resolveTwitchAccountContext } from "./config.js";
 import { twitchOutbound } from "./outbound.js";
 import type { ChannelMessageActionAdapter, ChannelMessageActionContext } from "./types.js";
 
@@ -68,7 +69,7 @@ export const twitchMessageActions: ChannelMessageActionAdapter = {
   /**
    * List available actions for this channel.
    */
-  listActions: () => [...TWITCH_ACTIONS],
+  describeMessageTool: () => ({ actions: [...TWITCH_ACTIONS] }),
 
   /**
    * Check if an action is supported.
@@ -130,12 +131,12 @@ export const twitchMessageActions: ChannelMessageActionAdapter = {
 
     const message = readStringParam(ctx.params, "message", { required: true });
     const to = readStringParam(ctx.params, "to", { required: false });
-    const accountId = ctx.accountId ?? DEFAULT_ACCOUNT_ID;
+    const accountId = ctx.accountId ?? resolveTwitchAccountContext(ctx.cfg).accountId;
 
-    const account = getAccountConfig(ctx.cfg, accountId);
+    const { account, availableAccountIds } = resolveTwitchAccountContext(ctx.cfg, accountId);
     if (!account) {
       return errorResponse(
-        `Account not found: ${accountId}. Available accounts: ${Object.keys(ctx.cfg.channels?.twitch?.accounts ?? {}).join(", ") || "none"}`,
+        `Account not found: ${accountId}. Available accounts: ${availableAccountIds.join(", ") || "none"}`,
       );
     }
 
@@ -167,7 +168,7 @@ export const twitchMessageActions: ChannelMessageActionAdapter = {
         details: { ok: true },
       };
     } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
+      const errorMsg = formatErrorMessage(error);
       return errorResponse(errorMsg);
     }
   },

package/src/client-manager-registry.ts

@@ -85,31 +85,3 @@ export async function removeClientManager(accountId: string): Promise<void> {
   registry.delete(accountId);
   entry.logger.info(`Unregistered client manager for account: ${accountId}`);
 }
-
-/**
- * Disconnect and remove all client managers from the registry.
- *
- * @returns Promise that resolves when all cleanup is complete
- */
-export async function removeAllClientManagers(): Promise<void> {
-  const promises = [...registry.keys()].map((accountId) => removeClientManager(accountId));
-  await Promise.all(promises);
-}
-
-/**
- * Get the number of registered client managers.
- *
- * @returns The count of registered managers
- */
-export function getRegisteredClientManagerCount(): number {
-  return registry.size;
-}
-
-/**
- * Clear all client managers without disconnecting.
- *
- * This is primarily for testing purposes.
- */
-export function _clearAllClientManagersForTest(): void {
-  registry.clear();
-}