@openclaw/twitch 2026.2.21 → 2026.5.2-beta.1

package/src/config-schema.test.ts

@@ -0,0 +1,46 @@
+import AjvPkg from "ajv";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+import { describe, expect, it } from "vitest";
+import { TwitchConfigSchema } from "./config-schema.js";
+
+function validateTwitchConfig(value: unknown): boolean {
+  const Ajv = AjvPkg as unknown as new (opts?: object) => import("ajv").default;
+  const schema = buildChannelConfigSchema(TwitchConfigSchema).schema;
+  const validate = new Ajv({ allErrors: true, strict: false }).compile(schema);
+  const ok = validate(value);
+  if (!ok) {
+    throw new Error(`expected valid Twitch config: ${JSON.stringify(validate.errors)}`);
+  }
+  return true;
+}
+
+describe("TwitchConfigSchema JSON schema", () => {
+  it("accepts single-account channel config with base fields", () => {
+    expect(
+      validateTwitchConfig({
+        enabled: false,
+        username: "openclaw",
+        accessToken: "oauth:test",
+        clientId: "test-client-id",
+        channel: "openclaw-test",
+      }),
+    ).toBe(true);
+  });
+
+  it("accepts multi-account channel config with defaultAccount", () => {
+    expect(
+      validateTwitchConfig({
+        enabled: true,
+        defaultAccount: "stream",
+        accounts: {
+          stream: {
+            username: "openclaw",
+            accessToken: "oauth:test",
+            clientId: "test-client-id",
+            channel: "openclaw-test",
+          },
+        },
+      }),
+    ).toBe(true);
+  });
+});

package/src/config-schema.ts

@@ -1,15 +1,12 @@
-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
  */
 const TwitchRoleSchema = z.enum(["moderator", "owner", "vip", "subscriber", "all"]);
 
-/**
- * Twitch account configuration schema
- */
-const TwitchAccountSchema = z.object({
+const TwitchAccountShape = {
   /** Twitch username */
   username: z.string(),
   /** Twitch OAuth access token (requires chat:read and chat:write scopes) */
@@ -36,16 +33,22 @@ const TwitchAccountSchema = z.object({
   expiresIn: z.number().nullable().optional(),
   /** Timestamp when token was obtained (optional, for token refresh tracking) */
   obtainmentTimestamp: z.number().optional(),
-});
+};
+
+/**
+ * Twitch account configuration schema
+ */
+const TwitchAccountSchema = z.object(TwitchAccountShape);
 
 /**
  * Base configuration properties shared by both single and multi-account modes
  */
-const TwitchConfigBaseSchema = z.object({
+const TwitchConfigBaseShape = {
   name: z.string().optional(),
   enabled: z.boolean().optional(),
   markdown: MarkdownConfigSchema.optional(),
-});
+  defaultAccount: z.string().optional(),
+};
 
 /**
  * Simplified single-account configuration schema
@@ -53,24 +56,25 @@ const TwitchConfigBaseSchema = z.object({
  * Use this for single-account setups. Properties are at the top level,
  * creating an implicit "default" account.
  */
-const SimplifiedSchema = z.intersection(TwitchConfigBaseSchema, TwitchAccountSchema);
+const SimplifiedSchema = z.object({
+  ...TwitchConfigBaseShape,
+  ...TwitchAccountShape,
+});
 
 /**
  * Multi-account configuration schema
  *
  * Use this for multi-account setups. Each key is an account ID (e.g., "default", "secondary").
  */
-const MultiAccountSchema = z.intersection(
-  TwitchConfigBaseSchema,
-  z
-    .object({
-      /** Per-account configuration (for multi-account setups) */
-      accounts: z.record(z.string(), TwitchAccountSchema),
-    })
-    .refine((val) => Object.keys(val.accounts || {}).length > 0, {
-      message: "accounts must contain at least one entry",
-    }),
-);
+const MultiAccountSchema = z
+  .object({
+    ...TwitchConfigBaseShape,
+    /** Per-account configuration (for multi-account setups) */
+    accounts: z.record(z.string(), TwitchAccountSchema),
+  })
+  .refine((val) => Object.keys(val.accounts || {}).length > 0, {
+    message: "accounts must contain at least one entry",
+  });
 
 /**
  * Twitch plugin configuration schema

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

package/src/monitor.ts

@@ -5,8 +5,11 @@
  * resolves agent routes, and handles replies.
  */
 
-import type { ReplyPayload, OpenClawConfig } from "openclaw/plugin-sdk";
-import { createReplyPrefixOptions } from "openclaw/plugin-sdk";
+import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
+import type { MarkdownTableMode, OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import type { ReplyPayload } from "openclaw/plugin-sdk/reply-runtime";
+import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/text-runtime";
 import { checkTwitchAccessControl } from "./access-control.js";
 import { getOrCreateClientManager } from "./client-manager-registry.js";
 import { getTwitchRuntime } from "./runtime.js";
@@ -48,91 +51,129 @@ async function processTwitchMessage(params: {
   const { message, account, accountId, config, runtime, core, statusSink } = params;
   const cfg = config as OpenClawConfig;
 
-  const route = core.channel.routing.resolveAgentRoute({
-    cfg,
+  await core.channel.turn.run({
     channel: "twitch",
     accountId,
-    peer: {
-      kind: "group", // Twitch chat is always group-like
-      id: message.channel,
-    },
-  });
-
-  const rawBody = message.message;
-  const body = core.channel.reply.formatAgentEnvelope({
-    channel: "Twitch",
-    from: message.displayName ?? message.username,
-    timestamp: message.timestamp?.getTime(),
-    envelope: core.channel.reply.resolveEnvelopeFormatOptions(cfg),
-    body: rawBody,
-  });
-
-  const ctxPayload = core.channel.reply.finalizeInboundContext({
-    Body: body,
-    BodyForAgent: rawBody,
-    RawBody: rawBody,
-    CommandBody: rawBody,
-    From: `twitch:user:${message.userId}`,
-    To: `twitch:channel:${message.channel}`,
-    SessionKey: route.sessionKey,
-    AccountId: route.accountId,
-    ChatType: "group",
-    ConversationLabel: message.channel,
-    SenderName: message.displayName ?? message.username,
-    SenderId: message.userId,
-    SenderUsername: message.username,
-    Provider: "twitch",
-    Surface: "twitch",
-    MessageSid: message.id,
-    OriginatingChannel: "twitch",
-    OriginatingTo: `twitch:channel:${message.channel}`,
-  });
-
-  const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
-    agentId: route.agentId,
-  });
-  await core.channel.session.recordInboundSession({
-    storePath,
-    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-    ctx: ctxPayload,
-    onRecordError: (err) => {
-      runtime.error?.(`Failed updating session meta: ${String(err)}`);
-    },
-  });
-
-  const tableMode = core.channel.text.resolveMarkdownTableMode({
-    cfg,
-    channel: "twitch",
-    accountId,
-  });
-  const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
-    cfg,
-    agentId: route.agentId,
-    channel: "twitch",
-    accountId,
-  });
-
-  await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-    ctx: ctxPayload,
-    cfg,
-    dispatcherOptions: {
-      ...prefixOptions,
-      deliver: async (payload) => {
-        await deliverTwitchReply({
-          payload,
-          channel: message.channel,
-          account,
+    raw: message,
+    adapter: {
+      ingest: (incoming) => ({
+        id: incoming.id ?? `${incoming.channel}:${incoming.timestamp?.getTime() ?? Date.now()}`,
+        timestamp: incoming.timestamp?.getTime(),
+        rawText: incoming.message,
+        textForAgent: incoming.message,
+        textForCommands: incoming.message,
+        raw: incoming,
+      }),
+      resolveTurn: (input) => {
+        const route = core.channel.routing.resolveAgentRoute({
+          cfg,
+          channel: "twitch",
+          accountId,
+          peer: {
+            kind: "group",
+            id: message.channel,
+          },
+        });
+        const senderId = message.userId ?? message.username;
+        const fromLabel = message.displayName ?? message.username;
+        const body = core.channel.reply.formatAgentEnvelope({
+          channel: "Twitch",
+          from: fromLabel,
+          timestamp: input.timestamp,
+          envelope: core.channel.reply.resolveEnvelopeFormatOptions(cfg),
+          body: input.rawText,
+        });
+        const ctxPayload = core.channel.turn.buildContext({
+          channel: "twitch",
           accountId,
-          config,
-          tableMode,
-          runtime,
-          statusSink,
+          messageId: input.id,
+          timestamp: input.timestamp,
+          from: `twitch:user:${senderId}`,
+          sender: {
+            id: senderId,
+            name: fromLabel,
+            username: message.username,
+          },
+          conversation: {
+            kind: "group",
+            id: message.channel,
+            label: message.channel,
+            routePeer: {
+              kind: "group",
+              id: message.channel,
+            },
+          },
+          route: {
+            agentId: route.agentId,
+            accountId: route.accountId,
+            routeSessionKey: route.sessionKey,
+          },
+          reply: {
+            to: `twitch:channel:${message.channel}`,
+            originatingTo: `twitch:channel:${message.channel}`,
+          },
+          message: {
+            body,
+            rawBody: input.rawText,
+            bodyForAgent: input.textForAgent,
+            commandBody: input.textForCommands,
+            envelopeFrom: fromLabel,
+          },
         });
+        const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+          agentId: route.agentId,
+        });
+        const tableMode = core.channel.text.resolveMarkdownTableMode({
+          cfg,
+          channel: "twitch",
+          accountId,
+        });
+        const { onModelSelected, ...replyPipeline } = createChannelReplyPipeline({
+          cfg,
+          agentId: route.agentId,
+          channel: "twitch",
+          accountId,
+        });
+        return {
+          cfg,
+          channel: "twitch",
+          accountId,
+          agentId: route.agentId,
+          routeSessionKey: route.sessionKey,
+          storePath,
+          ctxPayload,
+          recordInboundSession: core.channel.session.recordInboundSession,
+          dispatchReplyWithBufferedBlockDispatcher:
+            core.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+          delivery: {
+            deliver: async (payload) => {
+              await deliverTwitchReply({
+                payload,
+                channel: message.channel,
+                account,
+                accountId,
+                config,
+                tableMode,
+                runtime,
+                statusSink,
+              });
+            },
+            onError: (err, info) => {
+              runtime.error?.(`Twitch ${info.kind} reply failed: ${String(err)}`);
+            },
+          },
+          dispatcherOptions: replyPipeline,
+          replyOptions: {
+            onModelSelected,
+          },
+          record: {
+            onRecordError: (err) => {
+              runtime.error?.(`Failed updating session meta: ${String(err)}`);
+            },
+          },
+        };
       },
     },
-    replyOptions: {
-      onModelSelected,
-    },
   });
 }
 
@@ -145,7 +186,7 @@ async function deliverTwitchReply(params: {
   account: TwitchAccountConfig;
   accountId: string;
   config: unknown;
-  tableMode: "off" | "plain" | "markdown" | "bullets" | "code";
+  tableMode: MarkdownTableMode;
   runtime: TwitchRuntimeEnv;
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
 }): Promise<void> {
@@ -220,7 +261,7 @@ export async function monitorTwitchProvider(
       accountId,
     );
   } catch (error) {
-    const errorMsg = error instanceof Error ? error.message : String(error);
+    const errorMsg = formatErrorMessage(error);
     runtime.error?.(`Failed to connect: ${errorMsg}`);
     throw error;
   }
@@ -231,8 +272,8 @@ export async function monitorTwitchProvider(
     }
 
     // Access control check
-    const botUsername = account.username.toLowerCase();
-    if (message.username.toLowerCase() === botUsername) {
+    const botUsername = normalizeLowercaseStringOrEmpty(account.username);
+    if (normalizeLowercaseStringOrEmpty(message.username) === botUsername) {
       return; // Ignore own messages
     }