@openclaw/twitch 2026.2.21 → 2026.5.1-beta.1

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();
-}

package/src/config-schema.ts

@@ -1,5 +1,5 @@
-import { MarkdownConfigSchema } from "openclaw/plugin-sdk";
-import { z } from "zod";
+import { MarkdownConfigSchema } from "openclaw/plugin-sdk/channel-config-primitives";
+import { z } from "openclaw/plugin-sdk/zod";
 
 /**
  * Twitch user roles that can be allowed to interact with the bot

package/src/config.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vitest";
-import { getAccountConfig } from "./config.js";
+import {
+  getAccountConfig,
+  listAccountIds,
+  resolveDefaultTwitchAccountId,
+  resolveTwitchAccountContext,
+} from "./config.js";
 
 describe("getAccountConfig", () => {
   const mockMultiAccountConfig = {
@@ -49,6 +54,30 @@ describe("getAccountConfig", () => {
     expect(result?.username).toBe("secondbot");
   });
 
+  it("normalizes account ids without reading inherited account properties", () => {
+    const accounts = Object.create({
+      inherited: {
+        username: "inherited-bot",
+        accessToken: "oauth:inherited",
+      },
+    }) as Record<string, unknown>;
+    accounts.Secondary = {
+      username: "secondbot",
+      accessToken: "oauth:secondary",
+    };
+
+    const cfg = {
+      channels: {
+        twitch: {
+          accounts,
+        },
+      },
+    };
+
+    expect(getAccountConfig(cfg, "SECONDARY\r\n")).toMatchObject({ username: "secondbot" });
+    expect(getAccountConfig(cfg, "inherited")).toBeNull();
+  });
+
   it("returns null for non-existent account ID", () => {
     const result = getAccountConfig(mockMultiAccountConfig, "nonexistent");
 
@@ -85,3 +114,120 @@ describe("getAccountConfig", () => {
     expect(result).toBeNull();
   });
 });
+
+describe("listAccountIds", () => {
+  it("includes the implicit default account from simplified config", () => {
+    expect(
+      listAccountIds({
+        channels: {
+          twitch: {
+            username: "testbot",
+            accessToken: "oauth:test123",
+          },
+        },
+      } as Parameters<typeof listAccountIds>[0]),
+    ).toEqual(["default"]);
+  });
+
+  it("combines explicit accounts with the implicit default account once", () => {
+    expect(
+      listAccountIds({
+        channels: {
+          twitch: {
+            username: "testbot",
+            accounts: {
+              default: { username: "testbot" },
+              secondary: { username: "secondbot" },
+            },
+          },
+        },
+      } as Parameters<typeof listAccountIds>[0]),
+    ).toEqual(["default", "secondary"]);
+  });
+
+  it("normalizes configured account ids", () => {
+    expect(
+      listAccountIds({
+        channels: {
+          twitch: {
+            accounts: {
+              Secondary: { username: "secondbot" },
+              "Alerts\r\n\u001b[31m": { username: "alerts" },
+            },
+          },
+        },
+      } as Parameters<typeof listAccountIds>[0]),
+    ).toEqual(["alerts-31m", "secondary"]);
+  });
+});
+
+describe("resolveDefaultTwitchAccountId", () => {
+  it("prefers channels.twitch.defaultAccount when configured", () => {
+    expect(
+      resolveDefaultTwitchAccountId({
+        channels: {
+          twitch: {
+            defaultAccount: "secondary",
+            accounts: {
+              default: { username: "default" },
+              secondary: { username: "secondary" },
+            },
+          },
+        },
+      } as Parameters<typeof resolveDefaultTwitchAccountId>[0]),
+    ).toBe("secondary");
+  });
+});
+
+describe("resolveTwitchAccountContext", () => {
+  it("uses configured defaultAccount when accountId is omitted", () => {
+    const context = resolveTwitchAccountContext({
+      channels: {
+        twitch: {
+          defaultAccount: "secondary",
+          accounts: {
+            default: {
+              username: "default-bot",
+              accessToken: "oauth:default-token",
+            },
+            secondary: {
+              username: "second-bot",
+              accessToken: "oauth:second-token",
+            },
+          },
+        },
+      },
+    } as Parameters<typeof resolveTwitchAccountContext>[0]);
+
+    expect(context.accountId).toBe("secondary");
+    expect(context.account?.username).toBe("second-bot");
+  });
+
+  it("keeps account and token lookup aligned after account id normalization", () => {
+    const context = resolveTwitchAccountContext(
+      {
+        channels: {
+          twitch: {
+            accounts: {
+              Secondary: {
+                username: "second-bot",
+                accessToken: "oauth:second-token",
+                clientId: "second-client",
+                channel: "#second",
+              },
+            },
+          },
+        },
+      } as Parameters<typeof resolveTwitchAccountContext>[0],
+      "secondary",
+    );
+
+    expect(context.accountId).toBe("secondary");
+    expect(context.account?.username).toBe("second-bot");
+    expect(context.tokenResolution).toEqual({
+      token: "oauth:second-token",
+      source: "config",
+    });
+    expect(context.configured).toBe(true);
+  });
+});

package/src/config.ts

@@ -1,11 +1,26 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import {
+  listCombinedAccountIds,
+  normalizeAccountId,
+  resolveNormalizedAccountEntry,
+} from "openclaw/plugin-sdk/account-resolution";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveTwitchToken, type TwitchTokenResolution } from "./token.js";
 import type { TwitchAccountConfig } from "./types.js";
+import { isAccountConfigured } from "./utils/twitch.js";
 
 /**
  * Default account ID for Twitch
  */
 export const DEFAULT_ACCOUNT_ID = "default";
 
+export type ResolvedTwitchAccountContext = {
+  accountId: string;
+  account: TwitchAccountConfig | null;
+  tokenResolution: TwitchTokenResolution;
+  configured: boolean;
+  availableAccountIds: string[];
+};
+
 /**
  * Get account config from core config
  *
@@ -25,14 +40,19 @@ export function getAccountConfig(
   }
 
   const cfg = coreConfig as OpenClawConfig;
+  const normalizedAccountId = normalizeAccountId(accountId);
   const twitch = cfg.channels?.twitch;
   // Access accounts via unknown to handle union type (single-account vs multi-account)
   const twitchRaw = twitch as Record<string, unknown> | undefined;
   const accounts = twitchRaw?.accounts as Record<string, TwitchAccountConfig> | undefined;
 
   // For default account, check base-level config first
-  if (accountId === DEFAULT_ACCOUNT_ID) {
-    const accountFromAccounts = accounts?.[DEFAULT_ACCOUNT_ID];
+  if (normalizedAccountId === DEFAULT_ACCOUNT_ID) {
+    const accountFromAccounts = resolveNormalizedAccountEntry(
+      accounts,
+      DEFAULT_ACCOUNT_ID,
+      normalizeAccountId,
+    );
 
     // Base-level properties that can form an implicit default account
     const baseLevel = {
@@ -76,11 +96,12 @@ export function getAccountConfig(
   }
 
   // For non-default accounts, only check accounts object
-  if (!accounts || !accounts[accountId]) {
+  const account = resolveNormalizedAccountEntry(accounts, normalizedAccountId, normalizeAccountId);
+  if (!account) {
     return null;
   }
 
-  return accounts[accountId] as TwitchAccountConfig | null;
+  return account;
 }
 
 /**
@@ -94,13 +115,6 @@ export function listAccountIds(cfg: OpenClawConfig): string[] {
   const twitchRaw = twitch as Record<string, unknown> | undefined;
   const accountMap = twitchRaw?.accounts as Record<string, unknown> | undefined;
 
-  const ids: string[] = [];
-
-  // Add explicit accounts
-  if (accountMap) {
-    ids.push(...Object.keys(accountMap));
-  }
-
   // Add implicit "default" if base-level config exists and "default" not already present
   const hasBaseLevelConfig =
     twitchRaw &&
@@ -108,9 +122,56 @@ export function listAccountIds(cfg: OpenClawConfig): string[] {
       typeof twitchRaw.accessToken === "string" ||
       typeof twitchRaw.channel === "string");
 
-  if (hasBaseLevelConfig && !ids.includes(DEFAULT_ACCOUNT_ID)) {
-    ids.push(DEFAULT_ACCOUNT_ID);
+  return listCombinedAccountIds({
+    configuredAccountIds: Object.keys(accountMap ?? {}).map((accountId) =>
+      normalizeAccountId(accountId),
+    ),
+    implicitAccountId: hasBaseLevelConfig ? DEFAULT_ACCOUNT_ID : undefined,
+  });
+}
+
+export function resolveDefaultTwitchAccountId(cfg: OpenClawConfig): string {
+  const preferredRaw =
+    typeof cfg.channels?.twitch?.defaultAccount === "string"
+      ? cfg.channels.twitch.defaultAccount.trim()
+      : "";
+  const preferred = preferredRaw ? normalizeAccountId(preferredRaw) : "";
+  const ids = listAccountIds(cfg);
+  if (preferred && ids.includes(preferred)) {
+    return preferred;
+  }
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+    return DEFAULT_ACCOUNT_ID;
   }
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+export function resolveTwitchAccountContext(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): ResolvedTwitchAccountContext {
+  const resolvedAccountId = accountId?.trim()
+    ? normalizeAccountId(accountId)
+    : resolveDefaultTwitchAccountId(cfg);
+  const account = getAccountConfig(cfg, resolvedAccountId);
+  const tokenResolution = resolveTwitchToken(cfg, { accountId: resolvedAccountId });
+  return {
+    accountId: resolvedAccountId,
+    account,
+    tokenResolution,
+    configured: account ? isAccountConfigured(account, tokenResolution.token) : false,
+    availableAccountIds: listAccountIds(cfg),
+  };
+}
 
-  return ids;
+export function resolveTwitchSnapshotAccountId(
+  cfg: OpenClawConfig,
+  account: TwitchAccountConfig,
+): string {
+  const twitch = (cfg as Record<string, unknown>).channels as Record<string, unknown> | undefined;
+  const twitchCfg = twitch?.twitch as Record<string, unknown> | undefined;
+  const accountMap = (twitchCfg?.accounts as Record<string, unknown> | undefined) ?? {};
+  return (
+    Object.entries(accountMap).find(([, value]) => value === account)?.[0] ?? DEFAULT_ACCOUNT_ID
+  );
 }