@elizaos/plugin-twitch 2.0.0-alpha.3

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@elizaos/plugin-twitch",
+  "version": "2.0.0-alpha.3",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "bun run build.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@twurple/auth": "^7.2.0",
+    "@twurple/chat": "^7.2.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@elizaos/core": "2.0.0-alpha.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.0",
+    "typescript": "^5.3.0"
+  },
+  "milaidy": {
+    "platforms": [
+      "node"
+    ],
+    "runtime": "node",
+    "platformDetails": {
+      "node": "Node.js via main entry point"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/actions/joinChannel.ts

@@ -0,0 +1,147 @@
+/**
+ * Join channel action for Twitch plugin.
+ */
+
+import type {
+  Action,
+  ActionResult,
+  IAgentRuntime,
+  Memory,
+  State,
+} from "@elizaos/core";
+import {
+  composePromptFromState,
+  ModelType,
+  parseJSONObjectFromText,
+} from "@elizaos/core";
+import type { TwitchService } from "../service.js";
+import { normalizeChannel, TWITCH_SERVICE_NAME } from "../types.js";
+
+const JOIN_CHANNEL_TEMPLATE = `You are helping to extract a Twitch channel name.
+
+The user wants to join a Twitch channel.
+
+Recent conversation:
+{{recentMessages}}
+
+Extract the channel name to join (without the # prefix).
+
+Respond with a JSON object like:
+{
+  "channel": "channelname"
+}
+
+Only respond with the JSON object, no other text.`;
+
+export const joinChannel: Action = {
+  name: "TWITCH_JOIN_CHANNEL",
+  similes: ["JOIN_TWITCH_CHANNEL", "ENTER_CHANNEL", "CONNECT_CHANNEL"],
+  description: "Join a Twitch channel to listen and send messages",
+
+  validate: async (
+    _runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+  ): Promise<boolean> => {
+    return message.content.source === "twitch";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state?: State,
+    _options?: Record<string, unknown>,
+    callback?: (response: { text: string; source?: string }) => void,
+  ): Promise<ActionResult> => {
+    const twitchService =
+      runtime.getService<TwitchService>(TWITCH_SERVICE_NAME);
+
+    if (!twitchService || !twitchService.isConnected()) {
+      if (callback) {
+        callback({
+          text: "Twitch service is not available.",
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Twitch service not available" };
+    }
+
+    // Compose prompt
+    const currentState = state ?? (await runtime.composeState(message));
+    const prompt = await composePromptFromState({
+      template: JOIN_CHANNEL_TEMPLATE,
+      state: currentState,
+    });
+
+    // Extract channel name using LLM
+    let channelName: string | null = null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+        prompt,
+      });
+
+      const parsed = parseJSONObjectFromText(String(response));
+      if (parsed?.channel) {
+        channelName = normalizeChannel(String(parsed.channel));
+        break;
+      }
+    }
+
+    if (!channelName) {
+      if (callback) {
+        callback({
+          text: "I couldn't understand which channel you want me to join. Please specify the channel name.",
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Could not extract channel name" };
+    }
+
+    // Check if already joined
+    if (twitchService.getJoinedChannels().includes(channelName)) {
+      if (callback) {
+        callback({
+          text: `Already in channel #${channelName}.`,
+          source: "twitch",
+        });
+      }
+      return {
+        success: true,
+        data: { channel: channelName, alreadyJoined: true },
+      };
+    }
+
+    // Join channel
+    await twitchService.joinChannel(channelName);
+
+    if (callback) {
+      callback({
+        text: `Joined channel #${channelName}.`,
+        source: message.content.source as string,
+      });
+    }
+
+    return {
+      success: true,
+      data: {
+        channel: channelName,
+      },
+    };
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Join the channel shroud" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll join that channel.",
+          actions: ["TWITCH_JOIN_CHANNEL"],
+        },
+      },
+    ],
+  ],
+};

package/src/actions/leaveChannel.ts

@@ -0,0 +1,172 @@
+/**
+ * Leave channel action for Twitch plugin.
+ */
+
+import type {
+  Action,
+  ActionResult,
+  IAgentRuntime,
+  Memory,
+  State,
+} from "@elizaos/core";
+import {
+  composePromptFromState,
+  ModelType,
+  parseJSONObjectFromText,
+} from "@elizaos/core";
+import type { TwitchService } from "../service.js";
+import { normalizeChannel, TWITCH_SERVICE_NAME } from "../types.js";
+
+const LEAVE_CHANNEL_TEMPLATE = `You are helping to extract a Twitch channel name.
+
+The user wants to leave a Twitch channel.
+
+Recent conversation:
+{{recentMessages}}
+
+Currently joined channels: {{joinedChannels}}
+
+Extract the channel name to leave (without the # prefix).
+
+Respond with a JSON object like:
+{
+  "channel": "channelname"
+}
+
+Only respond with the JSON object, no other text.`;
+
+export const leaveChannel: Action = {
+  name: "TWITCH_LEAVE_CHANNEL",
+  similes: [
+    "LEAVE_TWITCH_CHANNEL",
+    "EXIT_CHANNEL",
+    "PART_CHANNEL",
+    "DISCONNECT_CHANNEL",
+  ],
+  description: "Leave a Twitch channel",
+
+  validate: async (
+    _runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+  ): Promise<boolean> => {
+    return message.content.source === "twitch";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state?: State,
+    _options?: Record<string, unknown>,
+    callback?: (response: { text: string; source?: string }) => void,
+  ): Promise<ActionResult> => {
+    const twitchService =
+      runtime.getService<TwitchService>(TWITCH_SERVICE_NAME);
+
+    if (!twitchService || !twitchService.isConnected()) {
+      if (callback) {
+        callback({
+          text: "Twitch service is not available.",
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Twitch service not available" };
+    }
+
+    const joinedChannels = twitchService.getJoinedChannels();
+
+    // Get or compose state
+    const currentState = state ?? (await runtime.composeState(message));
+
+    // Build state with joined channels
+    const enrichedState = {
+      ...currentState,
+      joinedChannels: joinedChannels.join(", "),
+    };
+
+    // Compose prompt
+    const prompt = await composePromptFromState({
+      template: LEAVE_CHANNEL_TEMPLATE,
+      state: enrichedState,
+    });
+
+    // Extract channel name using LLM
+    let channelName: string | null = null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+        prompt,
+      });
+
+      const parsed = parseJSONObjectFromText(String(response));
+      if (parsed?.channel) {
+        channelName = normalizeChannel(String(parsed.channel));
+        break;
+      }
+    }
+
+    if (!channelName) {
+      if (callback) {
+        callback({
+          text: "I couldn't understand which channel you want me to leave. Please specify the channel name.",
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Could not extract channel name" };
+    }
+
+    // Check if we're in that channel
+    if (!joinedChannels.includes(channelName)) {
+      if (callback) {
+        callback({
+          text: `Not currently in channel #${channelName}.`,
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Not in that channel" };
+    }
+
+    // Prevent leaving primary channel
+    if (channelName === twitchService.getPrimaryChannel()) {
+      if (callback) {
+        callback({
+          text: `Cannot leave the primary channel #${channelName}.`,
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Cannot leave primary channel" };
+    }
+
+    // Leave channel
+    await twitchService.leaveChannel(channelName);
+
+    if (callback) {
+      callback({
+        text: `Left channel #${channelName}.`,
+        source: message.content.source as string,
+      });
+    }
+
+    return {
+      success: true,
+      data: {
+        channel: channelName,
+      },
+    };
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Leave the channel shroud" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll leave that channel.",
+          actions: ["TWITCH_LEAVE_CHANNEL"],
+        },
+      },
+    ],
+  ],
+};

package/src/actions/listChannels.ts

@@ -0,0 +1,100 @@
+/**
+ * List channels action for Twitch plugin.
+ */
+
+import type {
+  Action,
+  ActionResult,
+  IAgentRuntime,
+  Memory,
+  State,
+} from "@elizaos/core";
+import type { TwitchService } from "../service.js";
+import { formatChannelForDisplay, TWITCH_SERVICE_NAME } from "../types.js";
+
+export const listChannels: Action = {
+  name: "TWITCH_LIST_CHANNELS",
+  similes: [
+    "LIST_TWITCH_CHANNELS",
+    "SHOW_CHANNELS",
+    "GET_CHANNELS",
+    "CURRENT_CHANNELS",
+  ],
+  description: "List all Twitch channels the bot is currently in",
+
+  validate: async (
+    _runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+  ): Promise<boolean> => {
+    return message.content.source === "twitch";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+    _options?: Record<string, unknown>,
+    callback?: (response: { text: string; source?: string }) => void,
+  ): Promise<ActionResult> => {
+    const twitchService =
+      runtime.getService<TwitchService>(TWITCH_SERVICE_NAME);
+
+    if (!twitchService || !twitchService.isConnected()) {
+      if (callback) {
+        callback({
+          text: "Twitch service is not available.",
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Twitch service not available" };
+    }
+
+    const joinedChannels = twitchService.getJoinedChannels();
+    const primaryChannel = twitchService.getPrimaryChannel();
+
+    // Format channel list
+    const channelList = joinedChannels.map((channel) => {
+      const displayName = formatChannelForDisplay(channel);
+      const isPrimary = channel === primaryChannel;
+      return isPrimary ? `${displayName} (primary)` : displayName;
+    });
+
+    const responseText =
+      joinedChannels.length > 0
+        ? `Currently in ${joinedChannels.length} channel(s):\n${channelList.map((c) => `• ${c}`).join("\n")}`
+        : "Not currently in any channels.";
+
+    if (callback) {
+      callback({
+        text: responseText,
+        source: message.content.source as string,
+      });
+    }
+
+    return {
+      success: true,
+      data: {
+        channelCount: joinedChannels.length,
+        channels: joinedChannels,
+        primaryChannel,
+      },
+    };
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "What channels are you in?" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll list the channels I'm currently in.",
+          actions: ["TWITCH_LIST_CHANNELS"],
+        },
+      },
+    ],
+  ],
+};

package/src/actions/sendMessage.ts

@@ -0,0 +1,177 @@
+/**
+ * Send message action for Twitch plugin.
+ */
+
+import type {
+  Action,
+  ActionResult,
+  IAgentRuntime,
+  Memory,
+  State,
+} from "@elizaos/core";
+import {
+  composePromptFromState,
+  ModelType,
+  parseJSONObjectFromText,
+} from "@elizaos/core";
+import type { TwitchService } from "../service.js";
+import { normalizeChannel, TWITCH_SERVICE_NAME } from "../types.js";
+
+const SEND_MESSAGE_TEMPLATE = `You are helping to extract send message parameters for Twitch chat.
+
+The user wants to send a message to a Twitch channel.
+
+Recent conversation:
+{{recentMessages}}
+
+Extract the following:
+1. text: The message text to send
+2. channel: The channel name to send to (without # prefix), or "current" for the current channel
+
+Respond with a JSON object like:
+{
+  "text": "The message to send",
+  "channel": "current"
+}
+
+Only respond with the JSON object, no other text.`;
+
+interface SendMessageParams {
+  text: string;
+  channel: string;
+}
+
+export const sendMessage: Action = {
+  name: "TWITCH_SEND_MESSAGE",
+  similes: [
+    "SEND_TWITCH_MESSAGE",
+    "TWITCH_CHAT",
+    "CHAT_TWITCH",
+    "SAY_IN_TWITCH",
+  ],
+  description: "Send a message to a Twitch channel",
+
+  validate: async (
+    _runtime: IAgentRuntime,
+    message: Memory,
+    _state?: State,
+  ): Promise<boolean> => {
+    return message.content.source === "twitch";
+  },
+
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state?: State,
+    _options?: Record<string, unknown>,
+    callback?: (response: { text: string; source?: string }) => void,
+  ): Promise<ActionResult> => {
+    const twitchService =
+      runtime.getService<TwitchService>(TWITCH_SERVICE_NAME);
+
+    if (!twitchService || !twitchService.isConnected()) {
+      if (callback) {
+        callback({
+          text: "Twitch service is not available.",
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Twitch service not available" };
+    }
+
+    // Get or compose state
+    const currentState = state ?? (await runtime.composeState(message));
+
+    // Compose prompt
+    const prompt = await composePromptFromState({
+      template: SEND_MESSAGE_TEMPLATE,
+      state: currentState,
+    });
+
+    // Extract parameters using LLM
+    let messageInfo: SendMessageParams | null = null;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+        prompt,
+      });
+
+      const parsed = parseJSONObjectFromText(String(response));
+      if (parsed?.text) {
+        messageInfo = {
+          text: String(parsed.text),
+          channel: String(parsed.channel || "current"),
+        };
+        break;
+      }
+    }
+
+    if (!messageInfo || !messageInfo.text) {
+      if (callback) {
+        callback({
+          text: "I couldn't understand what message you want me to send. Please try again.",
+          source: "twitch",
+        });
+      }
+      return { success: false, error: "Could not extract message parameters" };
+    }
+
+    // Determine target channel
+    let targetChannel = twitchService.getPrimaryChannel();
+    if (messageInfo.channel && messageInfo.channel !== "current") {
+      targetChannel = normalizeChannel(messageInfo.channel);
+    }
+
+    // Get channel from room context if available
+    if (currentState?.data?.room?.channelId) {
+      targetChannel = normalizeChannel(
+        currentState.data.room.channelId as string,
+      );
+    }
+
+    // Send message
+    const result = await twitchService.sendMessage(messageInfo.text, {
+      channel: targetChannel,
+    });
+
+    if (!result.success) {
+      if (callback) {
+        callback({
+          text: `Failed to send message: ${result.error}`,
+          source: "twitch",
+        });
+      }
+      return { success: false, error: result.error };
+    }
+
+    if (callback) {
+      callback({
+        text: "Message sent successfully.",
+        source: message.content.source as string,
+      });
+    }
+
+    return {
+      success: true,
+      data: {
+        channel: targetChannel,
+        messageId: result.messageId,
+      },
+    };
+  },
+
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Send a message to chat saying 'Hello everyone!'" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "I'll send that message to the chat.",
+          actions: ["TWITCH_SEND_MESSAGE"],
+        },
+      },
+    ],
+  ],
+};