@gguf/pigbot 0.0.1 → 0.0.3

package/extensions/twitch/src/actions.ts

@@ -0,0 +1,173 @@
+/**
+ * Twitch message actions adapter.
+ *
+ * Handles tool-based actions for Twitch, such as sending messages.
+ */
+
+import { DEFAULT_ACCOUNT_ID, getAccountConfig } from "./config.js";
+import { twitchOutbound } from "./outbound.js";
+import type { ChannelMessageActionAdapter, ChannelMessageActionContext } from "./types.js";
+
+/**
+ * Create a tool result with error content.
+ */
+function errorResponse(error: string) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({ ok: false, error }),
+      },
+    ],
+    details: { ok: false },
+  };
+}
+
+/**
+ * Read a string parameter from action arguments.
+ *
+ * @param args - Action arguments
+ * @param key - Parameter key
+ * @param options - Options for reading the parameter
+ * @returns The parameter value or undefined if not found
+ */
+function readStringParam(
+  args: Record<string, unknown>,
+  key: string,
+  options: { required?: boolean; trim?: boolean } = {},
+): string | undefined {
+  const value = args[key];
+  if (value === undefined || value === null) {
+    if (options.required) {
+      throw new Error(`Missing required parameter: ${key}`);
+    }
+    return undefined;
+  }
+
+  // Convert value to string safely
+  if (typeof value === "string") {
+    return options.trim !== false ? value.trim() : value;
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    const str = String(value);
+    return options.trim !== false ? str.trim() : str;
+  }
+
+  throw new Error(`Parameter ${key} must be a string, number, or boolean`);
+}
+
+/** Supported Twitch actions */
+const TWITCH_ACTIONS = new Set(["send" as const]);
+type TwitchAction = typeof TWITCH_ACTIONS extends Set<infer U> ? U : never;
+
+/**
+ * Twitch message actions adapter.
+ */
+export const twitchMessageActions: ChannelMessageActionAdapter = {
+  /**
+   * List available actions for this channel.
+   */
+  listActions: () => [...TWITCH_ACTIONS],
+
+  /**
+   * Check if an action is supported.
+   */
+  supportsAction: ({ action }) => TWITCH_ACTIONS.has(action as TwitchAction),
+
+  /**
+   * Extract tool send parameters from action arguments.
+   *
+   * Parses and validates the "to" and "message" parameters for sending.
+   *
+   * @param params - Arguments from the tool call
+   * @returns Parsed send parameters or null if invalid
+   *
+   * @example
+   * const result = twitchMessageActions.extractToolSend!({
+   *   args: { to: "#mychannel", message: "Hello!" }
+   * });
+   * // Returns: { to: "#mychannel", message: "Hello!" }
+   */
+  extractToolSend: ({ args }) => {
+    try {
+      const to = readStringParam(args, "to", { required: true });
+      const message = readStringParam(args, "message", { required: true });
+
+      if (!to || !message) {
+        return null;
+      }
+
+      return { to, message };
+    } catch {
+      return null;
+    }
+  },
+
+  /**
+   * Handle an action execution.
+   *
+   * Processes the "send" action to send messages to Twitch.
+   *
+   * @param ctx - Action context including action type, parameters, and config
+   * @returns Tool result with content or null if action not supported
+   *
+   * @example
+   * const result = await twitchMessageActions.handleAction!({
+   *   action: "send",
+   *   params: { message: "Hello Twitch!", to: "#mychannel" },
+   *   cfg: moltbotConfig,
+   *   accountId: "default",
+   * });
+   */
+  handleAction: async (
+    ctx: ChannelMessageActionContext,
+  ): Promise<{ content: Array<{ type: string; text: string }> } | null> => {
+    if (ctx.action !== "send") {
+      return null;
+    }
+
+    const message = readStringParam(ctx.params, "message", { required: true });
+    const to = readStringParam(ctx.params, "to", { required: false });
+    const accountId = ctx.accountId ?? DEFAULT_ACCOUNT_ID;
+
+    const account = getAccountConfig(ctx.cfg, accountId);
+    if (!account) {
+      return errorResponse(
+        `Account not found: ${accountId}. Available accounts: ${Object.keys(ctx.cfg.channels?.twitch?.accounts ?? {}).join(", ") || "none"}`,
+      );
+    }
+
+    // Use the channel from account config (or override with `to` parameter)
+    const targetChannel = to || account.channel;
+    if (!targetChannel) {
+      return errorResponse("No channel specified and no default channel in account config");
+    }
+
+    if (!twitchOutbound.sendText) {
+      return errorResponse("sendText not implemented");
+    }
+
+    try {
+      const result = await twitchOutbound.sendText({
+        cfg: ctx.cfg,
+        to: targetChannel,
+        text: message ?? "",
+        accountId,
+      });
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result),
+          },
+        ],
+        details: { ok: true },
+      };
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      return errorResponse(errorMsg);
+    }
+  },
+};

package/extensions/twitch/src/client-manager-registry.ts

@@ -0,0 +1,115 @@
+/**
+ * Client manager registry for Twitch plugin.
+ *
+ * Manages the lifecycle of TwitchClientManager instances across the plugin,
+ * ensuring proper cleanup when accounts are stopped or reconfigured.
+ */
+
+import { TwitchClientManager } from "./twitch-client.js";
+import type { ChannelLogSink } from "./types.js";
+
+/**
+ * Registry entry tracking a client manager and its associated account.
+ */
+type RegistryEntry = {
+  /** The client manager instance */
+  manager: TwitchClientManager;
+  /** The account ID this manager is for */
+  accountId: string;
+  /** Logger for this entry */
+  logger: ChannelLogSink;
+  /** When this entry was created */
+  createdAt: number;
+};
+
+/**
+ * Global registry of client managers.
+ * Keyed by account ID.
+ */
+const registry = new Map<string, RegistryEntry>();
+
+/**
+ * Get or create a client manager for an account.
+ *
+ * @param accountId - The account ID
+ * @param logger - Logger instance
+ * @returns The client manager
+ */
+export function getOrCreateClientManager(
+  accountId: string,
+  logger: ChannelLogSink,
+): TwitchClientManager {
+  const existing = registry.get(accountId);
+  if (existing) {
+    return existing.manager;
+  }
+
+  const manager = new TwitchClientManager(logger);
+  registry.set(accountId, {
+    manager,
+    accountId,
+    logger,
+    createdAt: Date.now(),
+  });
+
+  logger.info(`Registered client manager for account: ${accountId}`);
+  return manager;
+}
+
+/**
+ * Get an existing client manager for an account.
+ *
+ * @param accountId - The account ID
+ * @returns The client manager, or undefined if not registered
+ */
+export function getClientManager(accountId: string): TwitchClientManager | undefined {
+  return registry.get(accountId)?.manager;
+}
+
+/**
+ * Disconnect and remove a client manager from the registry.
+ *
+ * @param accountId - The account ID
+ * @returns Promise that resolves when cleanup is complete
+ */
+export async function removeClientManager(accountId: string): Promise<void> {
+  const entry = registry.get(accountId);
+  if (!entry) {
+    return;
+  }
+
+  // Disconnect the client manager
+  await entry.manager.disconnectAll();
+
+  // Remove from registry
+  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/extensions/twitch/src/config-schema.ts

@@ -0,0 +1,82 @@
+import { MarkdownConfigSchema } from "clawdbot/plugin-sdk";
+import { z } from "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({
+  /** Twitch username */
+  username: z.string(),
+  /** Twitch OAuth access token (requires chat:read and chat:write scopes) */
+  accessToken: z.string(),
+  /** Twitch client ID (from Twitch Developer Portal or twitchtokengenerator.com) */
+  clientId: z.string().optional(),
+  /** Channel name to join */
+  channel: z.string().min(1),
+  /** Enable this account */
+  enabled: z.boolean().optional(),
+  /** Allowlist of Twitch user IDs who can interact with the bot (use IDs for safety, not usernames) */
+  allowFrom: z.array(z.string()).optional(),
+  /** Roles allowed to interact with the bot (e.g., ["moderator", "vip", "subscriber"]) */
+  allowedRoles: z.array(TwitchRoleSchema).optional(),
+  /** Require @mention to trigger bot responses */
+  requireMention: z.boolean().optional(),
+  /** Twitch client secret (required for token refresh via RefreshingAuthProvider) */
+  clientSecret: z.string().optional(),
+  /** Refresh token (required for automatic token refresh) */
+  refreshToken: z.string().optional(),
+  /** Token expiry time in seconds (optional, for token refresh tracking) */
+  expiresIn: z.number().nullable().optional(),
+  /** Timestamp when token was obtained (optional, for token refresh tracking) */
+  obtainmentTimestamp: z.number().optional(),
+});
+
+/**
+ * Base configuration properties shared by both single and multi-account modes
+ */
+const TwitchConfigBaseSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  markdown: MarkdownConfigSchema.optional(),
+});
+
+/**
+ * Simplified single-account configuration schema
+ *
+ * Use this for single-account setups. Properties are at the top level,
+ * creating an implicit "default" account.
+ */
+const SimplifiedSchema = z.intersection(TwitchConfigBaseSchema, TwitchAccountSchema);
+
+/**
+ * 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",
+    }),
+);
+
+/**
+ * Twitch plugin configuration schema
+ *
+ * Supports two mutually exclusive patterns:
+ * 1. Simplified single-account: username, accessToken, clientId, channel at top level
+ * 2. Multi-account: accounts object with named account configs
+ *
+ * The union ensures clear discrimination between the two modes.
+ */
+export const TwitchConfigSchema = z.union([SimplifiedSchema, MultiAccountSchema]);

package/extensions/twitch/src/config.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+
+import { getAccountConfig } from "./config.js";
+
+describe("getAccountConfig", () => {
+  const mockMultiAccountConfig = {
+    channels: {
+      twitch: {
+        accounts: {
+          default: {
+            username: "testbot",
+            accessToken: "oauth:test123",
+          },
+          secondary: {
+            username: "secondbot",
+            accessToken: "oauth:secondary",
+          },
+        },
+      },
+    },
+  };
+
+  const mockSimplifiedConfig = {
+    channels: {
+      twitch: {
+        username: "testbot",
+        accessToken: "oauth:test123",
+      },
+    },
+  };
+
+  it("returns account config for valid account ID (multi-account)", () => {
+    const result = getAccountConfig(mockMultiAccountConfig, "default");
+
+    expect(result).not.toBeNull();
+    expect(result?.username).toBe("testbot");
+  });
+
+  it("returns account config for default account (simplified config)", () => {
+    const result = getAccountConfig(mockSimplifiedConfig, "default");
+
+    expect(result).not.toBeNull();
+    expect(result?.username).toBe("testbot");
+  });
+
+  it("returns non-default account from multi-account config", () => {
+    const result = getAccountConfig(mockMultiAccountConfig, "secondary");
+
+    expect(result).not.toBeNull();
+    expect(result?.username).toBe("secondbot");
+  });
+
+  it("returns null for non-existent account ID", () => {
+    const result = getAccountConfig(mockMultiAccountConfig, "nonexistent");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when core config is null", () => {
+    const result = getAccountConfig(null, "default");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when core config is undefined", () => {
+    const result = getAccountConfig(undefined, "default");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when channels are not defined", () => {
+    const result = getAccountConfig({}, "default");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when twitch is not defined", () => {
+    const result = getAccountConfig({ channels: {} }, "default");
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when accounts are not defined", () => {
+    const result = getAccountConfig({ channels: { twitch: {} } }, "default");
+
+    expect(result).toBeNull();
+  });
+});

package/extensions/twitch/src/config.ts

@@ -0,0 +1,116 @@
+import type { MoltbotConfig } from "clawdbot/plugin-sdk";
+import type { TwitchAccountConfig } from "./types.js";
+
+/**
+ * Default account ID for Twitch
+ */
+export const DEFAULT_ACCOUNT_ID = "default";
+
+/**
+ * Get account config from core config
+ *
+ * Handles two patterns:
+ * 1. Simplified single-account: base-level properties create implicit "default" account
+ * 2. Multi-account: explicit accounts object
+ *
+ * For "default" account, base-level properties take precedence over accounts.default
+ * For other accounts, only the accounts object is checked
+ */
+export function getAccountConfig(
+  coreConfig: unknown,
+  accountId: string,
+): TwitchAccountConfig | null {
+  if (!coreConfig || typeof coreConfig !== "object") {
+    return null;
+  }
+
+  const cfg = coreConfig as MoltbotConfig;
+  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];
+
+    // Base-level properties that can form an implicit default account
+    const baseLevel = {
+      username: typeof twitchRaw?.username === "string" ? twitchRaw.username : undefined,
+      accessToken: typeof twitchRaw?.accessToken === "string" ? twitchRaw.accessToken : undefined,
+      clientId: typeof twitchRaw?.clientId === "string" ? twitchRaw.clientId : undefined,
+      channel: typeof twitchRaw?.channel === "string" ? twitchRaw.channel : undefined,
+      enabled: typeof twitchRaw?.enabled === "boolean" ? twitchRaw.enabled : undefined,
+      allowFrom: Array.isArray(twitchRaw?.allowFrom) ? twitchRaw.allowFrom : undefined,
+      allowedRoles: Array.isArray(twitchRaw?.allowedRoles) ? twitchRaw.allowedRoles : undefined,
+      requireMention:
+        typeof twitchRaw?.requireMention === "boolean" ? twitchRaw.requireMention : undefined,
+      clientSecret:
+        typeof twitchRaw?.clientSecret === "string" ? twitchRaw.clientSecret : undefined,
+      refreshToken:
+        typeof twitchRaw?.refreshToken === "string" ? twitchRaw.refreshToken : undefined,
+      expiresIn: typeof twitchRaw?.expiresIn === "number" ? twitchRaw.expiresIn : undefined,
+      obtainmentTimestamp:
+        typeof twitchRaw?.obtainmentTimestamp === "number"
+          ? twitchRaw.obtainmentTimestamp
+          : undefined,
+    };
+
+    // Merge: base-level takes precedence over accounts.default
+    const merged: Partial<TwitchAccountConfig> = {
+      ...accountFromAccounts,
+      ...baseLevel,
+    } as Partial<TwitchAccountConfig>;
+
+    // Only return if we have at least username
+    if (merged.username) {
+      return merged as TwitchAccountConfig;
+    }
+
+    // Fall through to accounts.default if no base-level username
+    if (accountFromAccounts) {
+      return accountFromAccounts;
+    }
+
+    return null;
+  }
+
+  // For non-default accounts, only check accounts object
+  if (!accounts || !accounts[accountId]) {
+    return null;
+  }
+
+  return accounts[accountId] as TwitchAccountConfig | null;
+}
+
+/**
+ * List all configured account IDs
+ *
+ * Includes both explicit accounts and implicit "default" from base-level config
+ */
+export function listAccountIds(cfg: MoltbotConfig): string[] {
+  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 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 &&
+    (typeof twitchRaw.username === "string" ||
+      typeof twitchRaw.accessToken === "string" ||
+      typeof twitchRaw.channel === "string");
+
+  if (hasBaseLevelConfig && !ids.includes(DEFAULT_ACCOUNT_ID)) {
+    ids.push(DEFAULT_ACCOUNT_ID);
+  }
+
+  return ids;
+}