@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/actions/runtime.messaging.reactions.ts

@@ -0,0 +1,67 @@
+import {
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+} from "../runtime-api.js";
+import { discordMessagingActionRuntime } from "./runtime.messaging.runtime.js";
+import type { DiscordMessagingActionContext } from "./runtime.messaging.shared.js";
+
+export async function handleDiscordReactionMessagingAction(ctx: DiscordMessagingActionContext) {
+  switch (ctx.action) {
+    case "react": {
+      if (!ctx.isActionEnabled("reactions")) {
+        throw new Error("Discord reactions are disabled.");
+      }
+      const channelId = await ctx.resolveReactionChannelId();
+      const messageId = readStringParam(ctx.params, "messageId", {
+        required: true,
+      });
+      const { emoji, remove, isEmpty } = readReactionParams(ctx.params, {
+        removeErrorMessage: "Emoji is required to remove a Discord reaction.",
+      });
+      if (remove) {
+        await discordMessagingActionRuntime.removeReactionDiscord(
+          channelId,
+          messageId,
+          emoji,
+          ctx.withReactionRuntimeOptions(),
+        );
+        return jsonResult({ ok: true, removed: emoji });
+      }
+      if (isEmpty) {
+        const removed = await discordMessagingActionRuntime.removeOwnReactionsDiscord(
+          channelId,
+          messageId,
+          ctx.withReactionRuntimeOptions(),
+        );
+        return jsonResult({ ok: true, removed: removed.removed });
+      }
+      await discordMessagingActionRuntime.reactMessageDiscord(
+        channelId,
+        messageId,
+        emoji,
+        ctx.withReactionRuntimeOptions(),
+      );
+      return jsonResult({ ok: true, added: emoji });
+    }
+    case "reactions": {
+      if (!ctx.isActionEnabled("reactions")) {
+        throw new Error("Discord reactions are disabled.");
+      }
+      const channelId = await ctx.resolveReactionChannelId();
+      const messageId = readStringParam(ctx.params, "messageId", {
+        required: true,
+      });
+      const limit = readNumberParam(ctx.params, "limit");
+      const reactions = await discordMessagingActionRuntime.fetchReactionsDiscord(
+        channelId,
+        messageId,
+        ctx.withReactionRuntimeOptions({ limit }),
+      );
+      return jsonResult({ ok: true, reactions });
+    }
+    default:
+      return undefined;
+  }
+}

package/src/actions/runtime.messaging.runtime.ts

@@ -0,0 +1,73 @@
+import { readDiscordComponentSpec } from "../components.js";
+import type { KlawConfig } from "../runtime-api.js";
+import { sendDiscordComponentMessage } from "../send.components.js";
+import {
+  createThreadDiscord,
+  deleteMessageDiscord,
+  editMessageDiscord,
+  editChannelDiscord,
+  fetchChannelInfoDiscord,
+  fetchChannelPermissionsDiscord,
+  fetchMessageDiscord,
+  fetchReactionsDiscord,
+  listPinsDiscord,
+  listThreadsDiscord,
+  pinMessageDiscord,
+  reactMessageDiscord,
+  readMessagesDiscord,
+  removeOwnReactionsDiscord,
+  removeReactionDiscord,
+  searchMessagesDiscord,
+  sendMessageDiscord,
+  sendPollDiscord,
+  sendStickerDiscord,
+  sendVoiceMessageDiscord,
+  unpinMessageDiscord,
+} from "../send.js";
+import { resolveDiscordTargetChannelId } from "../send.shared.js";
+import { resolveDiscordChannelId } from "../targets.js";
+
+export const discordMessagingActionRuntime = {
+  createThreadDiscord,
+  deleteMessageDiscord,
+  editChannelDiscord,
+  editMessageDiscord,
+  fetchChannelInfoDiscord,
+  fetchChannelPermissionsDiscord,
+  fetchMessageDiscord,
+  fetchReactionsDiscord,
+  listPinsDiscord,
+  listThreadsDiscord,
+  pinMessageDiscord,
+  reactMessageDiscord,
+  readDiscordComponentSpec,
+  readMessagesDiscord,
+  removeOwnReactionsDiscord,
+  removeReactionDiscord,
+  resolveDiscordReactionTargetChannelId,
+  resolveDiscordChannelId,
+  searchMessagesDiscord,
+  sendDiscordComponentMessage,
+  sendMessageDiscord,
+  sendPollDiscord,
+  sendStickerDiscord,
+  sendVoiceMessageDiscord,
+  unpinMessageDiscord,
+};
+
+async function resolveDiscordReactionTargetChannelId(params: {
+  target: string;
+  cfg: KlawConfig;
+  accountId?: string;
+}): Promise<string> {
+  try {
+    return resolveDiscordChannelId(params.target);
+  } catch {
+    return (
+      await resolveDiscordTargetChannelId(params.target, {
+        cfg: params.cfg,
+        accountId: params.accountId,
+      })
+    ).channelId;
+  }
+}

package/src/actions/runtime.messaging.send.ts

@@ -0,0 +1,336 @@
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import {
+  assertMediaNotDataUrl,
+  jsonResult,
+  readBooleanParam,
+  readNumberParam,
+  readStringArrayParam,
+  readStringParam,
+  resolvePollMaxSelections,
+} from "../runtime-api.js";
+import { DiscordThreadInitialMessageError } from "../send.js";
+import { isThreadChannelType } from "../send.permissions.js";
+import type { DiscordSendComponents, DiscordSendEmbeds } from "../send.shared.js";
+import { discordMessagingActionRuntime } from "./runtime.messaging.runtime.js";
+import type { DiscordMessagingActionContext } from "./runtime.messaging.shared.js";
+
+function hasDiscordComponentObjectKeys(value: unknown): value is Record<string, unknown> {
+  return Boolean(
+    value &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value as Record<string, unknown>).length > 0,
+  );
+}
+
+async function appendDiscordThreadRenameResult(
+  ctx: DiscordMessagingActionContext,
+  params: {
+    payload: Record<string, unknown>;
+    target: string;
+    threadName?: string;
+  },
+) {
+  const threadName = params.threadName?.trim();
+  if (!threadName) {
+    return params.payload;
+  }
+  if (!ctx.isActionEnabled("channels")) {
+    return {
+      ...params.payload,
+      warning: "Discord threadName was ignored because Discord channel management is disabled.",
+    };
+  }
+
+  let channelId: string;
+  try {
+    channelId = discordMessagingActionRuntime.resolveDiscordChannelId(params.target);
+  } catch {
+    return {
+      ...params.payload,
+      warning: "Discord threadName was ignored because the send target is not a channel/thread.",
+    };
+  }
+
+  try {
+    const channel = await discordMessagingActionRuntime.fetchChannelInfoDiscord(
+      channelId,
+      ctx.withOpts(),
+    );
+    if (!isThreadChannelType(channel.type)) {
+      return {
+        ...params.payload,
+        warning: "Discord threadName was ignored because the send target is not a thread.",
+      };
+    }
+    const renamed = await discordMessagingActionRuntime.editChannelDiscord(
+      {
+        channelId,
+        name: threadName,
+      },
+      ctx.withOpts(),
+    );
+    return {
+      ...params.payload,
+      threadRename: {
+        ok: true,
+        channelId,
+        name: renamed.name ?? threadName,
+      },
+    };
+  } catch (error) {
+    return {
+      ...params.payload,
+      warning: `Discord message was sent, but thread rename failed: ${formatErrorMessage(error)}`,
+    };
+  }
+}
+
+export async function handleDiscordMessageSendAction(ctx: DiscordMessagingActionContext) {
+  switch (ctx.action) {
+    case "sticker": {
+      if (!ctx.isActionEnabled("stickers")) {
+        throw new Error("Discord stickers are disabled.");
+      }
+      const to = readStringParam(ctx.params, "to", { required: true });
+      const content = readStringParam(ctx.params, "content");
+      const stickerIds = readStringArrayParam(ctx.params, "stickerIds", {
+        required: true,
+        label: "stickerIds",
+      });
+      await discordMessagingActionRuntime.sendStickerDiscord(
+        to,
+        stickerIds,
+        ctx.withOpts({ content }),
+      );
+      return jsonResult({ ok: true });
+    }
+    case "poll": {
+      if (!ctx.isActionEnabled("polls")) {
+        throw new Error("Discord polls are disabled.");
+      }
+      const to = readStringParam(ctx.params, "to", { required: true });
+      const content = readStringParam(ctx.params, "content");
+      const question = readStringParam(ctx.params, "question", {
+        required: true,
+      });
+      const answers = readStringArrayParam(ctx.params, "answers", {
+        required: true,
+        label: "answers",
+      });
+      const allowMultiselect = readBooleanParam(ctx.params, "allowMultiselect");
+      const durationHours = readNumberParam(ctx.params, "durationHours");
+      const maxSelections = resolvePollMaxSelections(answers.length, allowMultiselect);
+      await discordMessagingActionRuntime.sendPollDiscord(
+        to,
+        { question, options: answers, maxSelections, durationHours },
+        ctx.withOpts({ content }),
+      );
+      return jsonResult({ ok: true });
+    }
+    case "sendMessage": {
+      if (!ctx.isActionEnabled("messages")) {
+        throw new Error("Discord message sends are disabled.");
+      }
+      const to = readStringParam(ctx.params, "to", { required: true });
+      const asVoice = ctx.params.asVoice === true;
+      const silent = ctx.params.silent === true;
+      const suppressEmbeds =
+        ctx.params.suppressEmbeds === undefined ? undefined : ctx.params.suppressEmbeds === true;
+      const rawComponents = ctx.params.components;
+      const componentSpec = hasDiscordComponentObjectKeys(rawComponents)
+        ? discordMessagingActionRuntime.readDiscordComponentSpec(rawComponents)
+        : null;
+      const components: DiscordSendComponents | undefined =
+        Array.isArray(rawComponents) || typeof rawComponents === "function"
+          ? (rawComponents as DiscordSendComponents)
+          : undefined;
+      const mediaUrl =
+        readStringParam(ctx.params, "mediaUrl", { trim: false }) ??
+        readStringParam(ctx.params, "path", { trim: false }) ??
+        readStringParam(ctx.params, "filePath", { trim: false });
+      const content = readStringParam(ctx.params, "content", {
+        required: !asVoice && !componentSpec && !components && !mediaUrl,
+        allowEmpty: true,
+      });
+      const filename = readStringParam(ctx.params, "filename");
+      const replyTo = readStringParam(ctx.params, "replyTo");
+      const threadName = readStringParam(ctx.params, "threadName");
+      const rawEmbeds = ctx.params.embeds;
+      const embeds: DiscordSendEmbeds | undefined = Array.isArray(rawEmbeds)
+        ? (rawEmbeds as DiscordSendEmbeds)
+        : undefined;
+      const sessionKey = readStringParam(ctx.params, "__sessionKey");
+      const agentId = readStringParam(ctx.params, "__agentId");
+
+      if (componentSpec) {
+        if (asVoice) {
+          throw new Error("Discord components cannot be sent as voice messages.");
+        }
+        if (embeds?.length) {
+          throw new Error("Discord components cannot include embeds.");
+        }
+        const normalizedContent = content?.trim() ? content : undefined;
+        const payload = componentSpec.text
+          ? componentSpec
+          : { ...componentSpec, text: normalizedContent };
+        const result = await discordMessagingActionRuntime.sendDiscordComponentMessage(
+          to,
+          payload,
+          {
+            ...ctx.withOpts(),
+            silent,
+            replyTo: replyTo ?? undefined,
+            sessionKey: sessionKey ?? undefined,
+            agentId: agentId ?? undefined,
+            mediaUrl: mediaUrl ?? undefined,
+            filename: filename ?? undefined,
+            mediaAccess: ctx.options?.mediaAccess,
+            mediaLocalRoots: ctx.options?.mediaLocalRoots,
+            mediaReadFile: ctx.options?.mediaReadFile,
+            ...(suppressEmbeds === undefined ? {} : { suppressEmbeds }),
+          },
+        );
+        return jsonResult(
+          await appendDiscordThreadRenameResult(ctx, {
+            payload: { ok: true, result, components: true },
+            target: to,
+            threadName,
+          }),
+        );
+      }
+
+      if (asVoice) {
+        if (!mediaUrl) {
+          throw new Error(
+            "Voice messages require a media file reference (mediaUrl, path, or filePath).",
+          );
+        }
+        if (content && content.trim()) {
+          throw new Error(
+            "Voice messages cannot include text content (Discord limitation). Remove the content parameter.",
+          );
+        }
+        assertMediaNotDataUrl(mediaUrl);
+        const result = await discordMessagingActionRuntime.sendVoiceMessageDiscord(to, mediaUrl, {
+          ...ctx.withOpts(),
+          replyTo,
+          silent,
+        });
+        return jsonResult(
+          await appendDiscordThreadRenameResult(ctx, {
+            payload: { ok: true, result, voiceMessage: true },
+            target: to,
+            threadName,
+          }),
+        );
+      }
+
+      const result = await discordMessagingActionRuntime.sendMessageDiscord(to, content ?? "", {
+        ...ctx.withOpts(),
+        mediaAccess: ctx.options?.mediaAccess,
+        mediaUrl,
+        filename: filename ?? undefined,
+        mediaLocalRoots: ctx.options?.mediaLocalRoots,
+        mediaReadFile: ctx.options?.mediaReadFile,
+        replyTo,
+        components,
+        embeds,
+        silent,
+        ...(suppressEmbeds === undefined ? {} : { suppressEmbeds }),
+      });
+      return jsonResult(
+        await appendDiscordThreadRenameResult(ctx, {
+          payload: { ok: true, result },
+          target: to,
+          threadName,
+        }),
+      );
+    }
+    case "threadCreate": {
+      if (!ctx.isActionEnabled("threads")) {
+        throw new Error("Discord threads are disabled.");
+      }
+      const channelId = ctx.resolveChannelId();
+      const name = readStringParam(ctx.params, "name", { required: true });
+      const messageId = readStringParam(ctx.params, "messageId");
+      const content = readStringParam(ctx.params, "content");
+      const autoArchiveMinutes = readNumberParam(ctx.params, "autoArchiveMinutes");
+      const appliedTags = readStringArrayParam(ctx.params, "appliedTags");
+      const payload = {
+        name,
+        messageId,
+        autoArchiveMinutes,
+        content,
+        appliedTags: appliedTags ?? undefined,
+      };
+      try {
+        const thread = await discordMessagingActionRuntime.createThreadDiscord(
+          channelId,
+          payload,
+          ctx.withOpts(),
+        );
+        return jsonResult({ ok: true, thread });
+      } catch (error) {
+        if (error instanceof DiscordThreadInitialMessageError) {
+          return jsonResult({
+            ok: true,
+            partial: true,
+            thread: error.thread,
+            warning: "Discord thread was created, but sending the initial message failed.",
+            initialMessageError: error.initialMessageError,
+          });
+        }
+        throw error;
+      }
+    }
+    case "threadList": {
+      if (!ctx.isActionEnabled("threads")) {
+        throw new Error("Discord threads are disabled.");
+      }
+      const guildId = readStringParam(ctx.params, "guildId", {
+        required: true,
+      });
+      const channelId = readStringParam(ctx.params, "channelId");
+      const includeArchived = readBooleanParam(ctx.params, "includeArchived");
+      const before = readStringParam(ctx.params, "before");
+      const limit = readNumberParam(ctx.params, "limit");
+      const threads = await discordMessagingActionRuntime.listThreadsDiscord(
+        {
+          guildId,
+          channelId,
+          includeArchived,
+          before,
+          limit,
+        },
+        ctx.withOpts(),
+      );
+      return jsonResult({ ok: true, threads });
+    }
+    case "threadReply": {
+      if (!ctx.isActionEnabled("threads")) {
+        throw new Error("Discord threads are disabled.");
+      }
+      const channelId = ctx.resolveChannelId();
+      const content = readStringParam(ctx.params, "content", {
+        required: true,
+      });
+      const mediaUrl = readStringParam(ctx.params, "mediaUrl");
+      const replyTo = readStringParam(ctx.params, "replyTo");
+      const result = await discordMessagingActionRuntime.sendMessageDiscord(
+        `channel:${channelId}`,
+        content,
+        {
+          ...ctx.withOpts(),
+          mediaUrl,
+          mediaLocalRoots: ctx.options?.mediaLocalRoots,
+          mediaReadFile: ctx.options?.mediaReadFile,
+          replyTo,
+        },
+      );
+      return jsonResult({ ok: true, result });
+    }
+    default:
+      return undefined;
+  }
+}

package/src/actions/runtime.messaging.shared.ts

@@ -0,0 +1,97 @@
+import { resolveDefaultDiscordAccountId } from "../accounts.js";
+import { createDiscordRuntimeAccountContext } from "../client.js";
+import {
+  type ActionGate,
+  readStringParam,
+  type DiscordActionConfig,
+  type KlawConfig,
+  withNormalizedTimestamp,
+} from "../runtime-api.js";
+import type { DiscordReactOpts } from "../send.types.js";
+import { discordMessagingActionRuntime } from "./runtime.messaging.runtime.js";
+import { createDiscordActionOptions } from "./runtime.shared.js";
+
+export type DiscordMessagingActionOptions = {
+  mediaAccess?: {
+    localRoots?: readonly string[];
+    readFile?: (filePath: string) => Promise<Buffer>;
+    workspaceDir?: string;
+  };
+  mediaLocalRoots?: readonly string[];
+  mediaReadFile?: (filePath: string) => Promise<Buffer>;
+};
+
+export type DiscordMessagingActionContext = {
+  action: string;
+  params: Record<string, unknown>;
+  isActionEnabled: ActionGate<DiscordActionConfig>;
+  cfg: KlawConfig;
+  options?: DiscordMessagingActionOptions;
+  accountId?: string;
+  resolveChannelId: () => string;
+  resolveReactionChannelId: () => Promise<string>;
+  withOpts: (extra?: Record<string, unknown>) => { cfg: KlawConfig; accountId?: string };
+  withReactionRuntimeOptions: <T extends Record<string, unknown> = Record<string, never>>(
+    extra?: T,
+  ) => DiscordReactOpts & T;
+  normalizeMessage: (message: unknown) => unknown;
+};
+
+export function createDiscordMessagingActionContext(params: {
+  action: string;
+  input: Record<string, unknown>;
+  isActionEnabled: ActionGate<DiscordActionConfig>;
+  cfg: KlawConfig;
+  options?: DiscordMessagingActionOptions;
+}): DiscordMessagingActionContext {
+  const accountId = readStringParam(params.input, "accountId");
+  const cfgOptions = { cfg: params.cfg };
+  const withOpts = (extra?: Record<string, unknown>) =>
+    createDiscordActionOptions({ cfg: params.cfg, accountId, extra });
+  const resolvedReactionAccountId = accountId ?? resolveDefaultDiscordAccountId(params.cfg);
+  const reactionRuntimeOptions = resolvedReactionAccountId
+    ? createDiscordRuntimeAccountContext({
+        cfg: params.cfg,
+        accountId: resolvedReactionAccountId,
+      })
+    : cfgOptions;
+  return {
+    action: params.action,
+    params: params.input,
+    isActionEnabled: params.isActionEnabled,
+    cfg: params.cfg,
+    options: params.options,
+    accountId,
+    resolveChannelId: () =>
+      discordMessagingActionRuntime.resolveDiscordChannelId(
+        readStringParam(params.input, "channelId", {
+          required: true,
+        }),
+      ),
+    resolveReactionChannelId: async () => {
+      const target =
+        readStringParam(params.input, "channelId") ??
+        readStringParam(params.input, "to", { required: true });
+      return await discordMessagingActionRuntime.resolveDiscordReactionTargetChannelId({
+        target,
+        cfg: params.cfg,
+        accountId: resolvedReactionAccountId,
+      });
+    },
+    withOpts,
+    withReactionRuntimeOptions: (extra) =>
+      ({
+        ...(reactionRuntimeOptions ?? cfgOptions),
+        ...extra,
+      }) as DiscordReactOpts & NonNullable<typeof extra>,
+    normalizeMessage: (message: unknown) => {
+      if (!message || typeof message !== "object") {
+        return message;
+      }
+      return withNormalizedTimestamp(
+        message as Record<string, unknown>,
+        (message as { timestamp?: unknown }).timestamp,
+      );
+    },
+  };
+}

package/src/actions/runtime.messaging.ts

@@ -0,0 +1,37 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ActionGate, DiscordActionConfig, KlawConfig } from "../runtime-api.js";
+import { handleDiscordMessageManagementAction } from "./runtime.messaging.messages.js";
+import { handleDiscordReactionMessagingAction } from "./runtime.messaging.reactions.js";
+import { handleDiscordMessageSendAction } from "./runtime.messaging.send.js";
+import {
+  createDiscordMessagingActionContext,
+  type DiscordMessagingActionOptions,
+} from "./runtime.messaging.shared.js";
+export { discordMessagingActionRuntime } from "./runtime.messaging.runtime.js";
+
+export async function handleDiscordMessagingAction(
+  action: string,
+  params: Record<string, unknown>,
+  isActionEnabled: ActionGate<DiscordActionConfig>,
+  cfg: KlawConfig,
+  options?: DiscordMessagingActionOptions,
+): Promise<AgentToolResult<unknown>> {
+  if (!cfg) {
+    throw new Error("Discord messaging actions require a resolved runtime config.");
+  }
+  const ctx = createDiscordMessagingActionContext({
+    action,
+    input: params,
+    isActionEnabled,
+    cfg,
+    options,
+  });
+  return (
+    (await handleDiscordReactionMessagingAction(ctx)) ??
+    (await handleDiscordMessageSendAction(ctx)) ??
+    (await handleDiscordMessageManagementAction(ctx)) ??
+    (() => {
+      throw new Error(`Unknown action: ${action}`);
+    })()
+  );
+}

package/src/actions/runtime.moderation-shared.ts

@@ -0,0 +1,48 @@
+import { PermissionFlagsBits } from "discord-api-types/v10";
+import { readNumberParam, readStringParam } from "../runtime-api.js";
+
+export type DiscordModerationAction = "timeout" | "kick" | "ban";
+
+export type DiscordModerationCommand = {
+  action: DiscordModerationAction;
+  guildId: string;
+  userId: string;
+  durationMinutes?: number;
+  until?: string;
+  reason?: string;
+  deleteMessageDays?: number;
+};
+
+const moderationPermissions: Record<DiscordModerationAction, bigint> = {
+  timeout: PermissionFlagsBits.ModerateMembers,
+  kick: PermissionFlagsBits.KickMembers,
+  ban: PermissionFlagsBits.BanMembers,
+};
+
+export function isDiscordModerationAction(action: string): action is DiscordModerationAction {
+  return action === "timeout" || action === "kick" || action === "ban";
+}
+
+export function requiredGuildPermissionForModerationAction(
+  action: DiscordModerationAction,
+): bigint {
+  return moderationPermissions[action];
+}
+
+export function readDiscordModerationCommand(
+  action: string,
+  params: Record<string, unknown>,
+): DiscordModerationCommand {
+  if (!isDiscordModerationAction(action)) {
+    throw new Error(`Unsupported Discord moderation action: ${action}`);
+  }
+  return {
+    action,
+    guildId: readStringParam(params, "guildId", { required: true }),
+    userId: readStringParam(params, "userId", { required: true }),
+    durationMinutes: readNumberParam(params, "durationMinutes", { integer: true }),
+    until: readStringParam(params, "until"),
+    reason: readStringParam(params, "reason"),
+    deleteMessageDays: readNumberParam(params, "deleteMessageDays", { integer: true }),
+  };
+}