@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/agent-components.modal.ts

@@ -0,0 +1,160 @@
+import { logError } from "klaw/plugin-sdk/logging-core";
+import { parseDiscordModalCustomIdForInteraction } from "../component-custom-id.js";
+import { resolveDiscordModalEntryWithPersistence } from "../components-registry.js";
+import { Modal, type ComponentData, type ModalInteraction } from "../internal/discord.js";
+import {
+  type AgentComponentContext,
+  ensureComponentUserAllowed,
+  formatModalSubmissionText,
+  parseDiscordModalId,
+  resolveAuthorizedComponentInteraction,
+  resolveInteractionCustomId,
+  resolveModalFieldValues,
+} from "./agent-components-helpers.js";
+import { dispatchDiscordComponentEvent } from "./agent-components.dispatch.js";
+import { dispatchPluginDiscordInteractiveEvent } from "./agent-components.plugin-interactive.js";
+
+export class DiscordComponentModal extends Modal {
+  override title = "Klaw form";
+  override customId = "__klaw_discord_component_modal_wildcard__";
+  override components = [];
+  override customIdParser = parseDiscordModalCustomIdForInteraction;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  async run(interaction: ModalInteraction, data: ComponentData): Promise<void> {
+    const modalId = parseDiscordModalId(data, resolveInteractionCustomId(interaction));
+    if (!modalId) {
+      logError("discord component modal: missing modal id");
+      try {
+        await interaction.reply({
+          content: "This form is no longer valid.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    const modalEntry = await resolveDiscordModalEntryWithPersistence({
+      id: modalId,
+      consume: false,
+    });
+    if (!modalEntry) {
+      try {
+        await interaction.reply({
+          content: "This form has expired.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    const unauthorizedReply = "You are not authorized to use this form.";
+    const authorized = await resolveAuthorizedComponentInteraction({
+      ctx: this.ctx,
+      interaction,
+      label: "discord component modal",
+      componentLabel: "form",
+      unauthorizedReply,
+      defer: false,
+    });
+    if (!authorized) {
+      return;
+    }
+    const {
+      interactionCtx,
+      channelCtx,
+      guildInfo,
+      allowNameMatching,
+      commandAuthorized,
+      user,
+      replyOpts,
+    } = authorized;
+
+    const modalAllowed = await ensureComponentUserAllowed({
+      entry: {
+        id: modalEntry.id,
+        kind: "button",
+        label: modalEntry.title,
+        allowedUsers: modalEntry.allowedUsers,
+      },
+      interaction,
+      user,
+      replyOpts,
+      componentLabel: "form",
+      unauthorizedReply,
+      allowNameMatching,
+    });
+    if (!modalAllowed) {
+      return;
+    }
+
+    const consumed = await resolveDiscordModalEntryWithPersistence({
+      id: modalId,
+      consume: !modalEntry.reusable,
+    });
+    if (!consumed) {
+      try {
+        await interaction.reply({
+          content: "This form has expired.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    if (consumed.callbackData) {
+      const fields = consumed.fields.map((field) => ({
+        id: field.id,
+        name: field.name,
+        values: resolveModalFieldValues(field, interaction),
+      }));
+      const pluginDispatch = await dispatchPluginDiscordInteractiveEvent({
+        ctx: this.ctx,
+        interaction,
+        interactionCtx,
+        channelCtx,
+        isAuthorizedSender: commandAuthorized,
+        data: consumed.callbackData,
+        kind: "modal",
+        fields,
+        messageId: consumed.messageId,
+      });
+      if (pluginDispatch === "handled") {
+        return;
+      }
+    }
+
+    try {
+      await interaction.acknowledge();
+    } catch (err) {
+      logError(`discord component modal: failed to acknowledge: ${String(err)}`);
+    }
+
+    const eventText = formatModalSubmissionText(consumed, interaction);
+    await dispatchDiscordComponentEvent({
+      ctx: this.ctx,
+      interaction,
+      interactionCtx,
+      channelCtx,
+      guildInfo,
+      eventText,
+      replyToId: consumed.messageId,
+      routeOverrides: {
+        sessionKey: consumed.sessionKey,
+        agentId: consumed.agentId,
+        accountId: consumed.accountId,
+      },
+    });
+  }
+}

package/src/monitor/agent-components.plugin-interactive.ts

@@ -0,0 +1,187 @@
+import { ChannelType } from "discord-api-types/v10";
+import { logError } from "klaw/plugin-sdk/logging-core";
+import {
+  dispatchDiscordPluginInteractiveHandler,
+  type DiscordInteractiveHandlerContext,
+} from "../interactive-dispatch.js";
+import type { TopLevelComponents } from "../internal/discord.js";
+import { editDiscordComponentMessage } from "../send.components.js";
+import {
+  resolveDiscordInteractionId,
+  type AgentComponentContext,
+  type AgentComponentInteraction,
+  type ComponentInteractionContext,
+  type DiscordChannelContext,
+} from "./agent-components-helpers.js";
+
+let conversationRuntimePromise: Promise<typeof import("./agent-components.runtime.js")> | undefined;
+
+async function loadConversationRuntime() {
+  conversationRuntimePromise ??= import("./agent-components.runtime.js");
+  return await conversationRuntimePromise;
+}
+
+export async function dispatchPluginDiscordInteractiveEvent(params: {
+  ctx: AgentComponentContext;
+  interaction: AgentComponentInteraction;
+  interactionCtx: ComponentInteractionContext;
+  channelCtx: DiscordChannelContext;
+  isAuthorizedSender: boolean;
+  data: string;
+  kind: "button" | "select" | "modal";
+  values?: string[];
+  fields?: Array<{ id: string; name: string; values: string[] }>;
+  messageId?: string;
+}): Promise<"handled" | "unmatched"> {
+  const normalizedConversationId =
+    params.interactionCtx.rawGuildId || params.channelCtx.channelType === ChannelType.GroupDM
+      ? `channel:${params.interactionCtx.channelId}`
+      : `user:${params.interactionCtx.userId}`;
+  let responded = false;
+  let acknowledged = false;
+  const updateOriginalMessage = async (input: {
+    text?: string;
+    components?: TopLevelComponents[];
+  }) => {
+    const payload = {
+      ...(input.text !== undefined ? { content: input.text } : {}),
+      ...(input.components !== undefined ? { components: input.components } : {}),
+    };
+    if (acknowledged) {
+      await params.interaction.reply(payload);
+      return;
+    }
+    if (!("update" in params.interaction) || typeof params.interaction.update !== "function") {
+      throw new Error("Discord interaction cannot update the source message");
+    }
+    await params.interaction.update(payload);
+  };
+  const respond: DiscordInteractiveHandlerContext["respond"] = {
+    acknowledge: async () => {
+      if (responded) {
+        return;
+      }
+      await params.interaction.acknowledge();
+      acknowledged = true;
+      responded = true;
+    },
+    reply: async ({ text, ephemeral = true }: { text: string; ephemeral?: boolean }) => {
+      responded = true;
+      await params.interaction.reply({
+        content: text,
+        ephemeral,
+      });
+    },
+    followUp: async ({ text, ephemeral = true }: { text: string; ephemeral?: boolean }) => {
+      responded = true;
+      await params.interaction.followUp({
+        content: text,
+        ephemeral,
+      });
+    },
+    editMessage: async (
+      input: Parameters<DiscordInteractiveHandlerContext["respond"]["editMessage"]>[0],
+    ) => {
+      const { text, components } = input;
+      responded = true;
+      await updateOriginalMessage({
+        text,
+        components: components as TopLevelComponents[] | undefined,
+      });
+    },
+    clearComponents: async (input?: { text?: string }) => {
+      responded = true;
+      await updateOriginalMessage({
+        text: input?.text,
+        components: [],
+      });
+    },
+  };
+  const conversationRuntime = await loadConversationRuntime();
+  const pluginBindingApproval = conversationRuntime.parsePluginBindingApprovalCustomId(params.data);
+  if (pluginBindingApproval) {
+    const { buildPluginBindingResolvedText, resolvePluginConversationBindingApproval } =
+      conversationRuntime;
+    try {
+      await respond.acknowledge();
+    } catch {
+      // Interaction may have expired; try to continue anyway.
+    }
+    const resolved = await resolvePluginConversationBindingApproval({
+      approvalId: pluginBindingApproval.approvalId,
+      decision: pluginBindingApproval.decision,
+      senderId: params.interactionCtx.userId,
+    });
+    const approvalMessageId = params.messageId?.trim() || params.interaction.message?.id?.trim();
+    if (approvalMessageId) {
+      try {
+        await editDiscordComponentMessage(
+          normalizedConversationId,
+          approvalMessageId,
+          {
+            text: buildPluginBindingResolvedText(resolved),
+          },
+          {
+            cfg: params.ctx.cfg,
+            accountId: params.ctx.accountId,
+          },
+        );
+      } catch (err) {
+        logError(`discord plugin binding approval: failed to clear prompt: ${String(err)}`);
+      }
+    }
+    if (resolved.status !== "approved") {
+      try {
+        await respond.followUp({
+          text: buildPluginBindingResolvedText(resolved),
+          ephemeral: true,
+        });
+      } catch (err) {
+        logError(`discord plugin binding approval: failed to follow up: ${String(err)}`);
+      }
+    }
+    return "handled";
+  }
+  const dispatched = await dispatchDiscordPluginInteractiveHandler({
+    data: params.data,
+    interactionId: resolveDiscordInteractionId(params.interaction),
+    ctx: {
+      accountId: params.ctx.accountId,
+      interactionId: resolveDiscordInteractionId(params.interaction),
+      conversationId: normalizedConversationId,
+      parentConversationId: params.channelCtx.parentId,
+      guildId: params.interactionCtx.rawGuildId,
+      senderId: params.interactionCtx.userId,
+      senderUsername: params.interactionCtx.username,
+      auth: { isAuthorizedSender: params.isAuthorizedSender },
+      interaction: {
+        kind: params.kind,
+        messageId: params.messageId,
+        values: params.values,
+        fields: params.fields,
+      },
+    },
+    respond,
+    onMatched: async () => {
+      try {
+        await respond.acknowledge();
+      } catch {
+        // Interaction may have expired before the plugin handler ran.
+      }
+    },
+  });
+  if (!dispatched.matched) {
+    return "unmatched";
+  }
+  if (dispatched.handled) {
+    if (!responded) {
+      try {
+        await respond.acknowledge();
+      } catch {
+        // Interaction may have expired after the handler finished.
+      }
+    }
+    return "handled";
+  }
+  return "unmatched";
+}

package/src/monitor/agent-components.runtime.ts

@@ -0,0 +1,14 @@
+export {
+  buildPluginBindingResolvedText,
+  parsePluginBindingApprovalCustomId,
+  recordInboundSession,
+  resolvePluginConversationBindingApproval,
+} from "klaw/plugin-sdk/conversation-runtime";
+export { dispatchPluginInteractiveHandler } from "klaw/plugin-sdk/plugin-runtime";
+export {
+  createReplyReferencePlanner,
+  dispatchReplyWithBufferedBlockDispatcher,
+  finalizeInboundContext,
+  resolveChunkMode,
+  resolveTextChunkLimit,
+} from "klaw/plugin-sdk/reply-runtime";

package/src/monitor/agent-components.system-controls.ts

@@ -0,0 +1,215 @@
+import type { APIStringSelectComponent } from "discord-api-types/v10";
+import { ButtonStyle } from "discord-api-types/v10";
+import { logDebug, logError } from "klaw/plugin-sdk/logging-core";
+import {
+  Button,
+  StringSelectMenu,
+  type ButtonInteraction,
+  type ComponentData,
+  type StringSelectMenuInteraction,
+} from "../internal/discord.js";
+import {
+  AGENT_BUTTON_KEY,
+  AGENT_SELECT_KEY,
+  ackComponentInteraction,
+  ensureAgentComponentInteractionAllowed,
+  parseAgentComponentData,
+  resolveAgentComponentRoute,
+  resolveInteractionContextWithDmAuth,
+  type AgentComponentContext,
+} from "./agent-components-helpers.js";
+import { enqueueSystemEvent } from "./agent-components.deps.runtime.js";
+
+export class AgentComponentButton extends Button {
+  override label = AGENT_BUTTON_KEY;
+  customId = `${AGENT_BUTTON_KEY}:seed=1`;
+  override style = ButtonStyle.Primary;
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  override async run(interaction: ButtonInteraction, data: ComponentData): Promise<void> {
+    const parsed = parseAgentComponentData(data);
+    if (!parsed) {
+      logError("agent button: failed to parse component data");
+      try {
+        await interaction.reply({
+          content: "This button is no longer valid.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    const { componentId } = parsed;
+
+    const interactionCtx = await resolveInteractionContextWithDmAuth({
+      ctx: this.ctx,
+      interaction,
+      label: "agent button",
+      componentLabel: "button",
+      defer: false,
+    });
+    if (!interactionCtx) {
+      return;
+    }
+    const {
+      channelId,
+      user,
+      username,
+      userId,
+      replyOpts,
+      rawGuildId,
+      isDirectMessage,
+      isGroupDm,
+      memberRoleIds,
+    } = interactionCtx;
+
+    const allowed = await ensureAgentComponentInteractionAllowed({
+      ctx: this.ctx,
+      interaction,
+      channelId,
+      rawGuildId,
+      memberRoleIds,
+      user,
+      replyOpts,
+      componentLabel: "button",
+      unauthorizedReply: "You are not authorized to use this button.",
+    });
+    if (!allowed) {
+      return;
+    }
+    const { parentId } = allowed;
+
+    const route = resolveAgentComponentRoute({
+      ctx: this.ctx,
+      rawGuildId,
+      memberRoleIds,
+      isDirectMessage,
+      isGroupDm,
+      userId,
+      channelId,
+      parentId,
+    });
+
+    const eventText = `[Discord component: ${componentId} clicked by ${username} (${userId})]`;
+
+    logDebug(`agent button: enqueuing event for channel ${channelId}: ${eventText}`);
+
+    enqueueSystemEvent(eventText, {
+      sessionKey: route.sessionKey,
+      contextKey: `discord:agent-button:${channelId}:${componentId}:${userId}`,
+      forceSenderIsOwnerFalse: true,
+      trusted: false,
+    });
+
+    await ackComponentInteraction({ interaction, replyOpts, label: "agent button" });
+  }
+}
+
+export class AgentSelectMenu extends StringSelectMenu {
+  customId = `${AGENT_SELECT_KEY}:seed=1`;
+  options: APIStringSelectComponent["options"] = [];
+  private ctx: AgentComponentContext;
+
+  constructor(ctx: AgentComponentContext) {
+    super();
+    this.ctx = ctx;
+  }
+
+  override async run(interaction: StringSelectMenuInteraction, data: ComponentData): Promise<void> {
+    const parsed = parseAgentComponentData(data);
+    if (!parsed) {
+      logError("agent select: failed to parse component data");
+      try {
+        await interaction.reply({
+          content: "This select menu is no longer valid.",
+          ephemeral: true,
+        });
+      } catch {
+        // Interaction may have expired
+      }
+      return;
+    }
+
+    const { componentId } = parsed;
+
+    const interactionCtx = await resolveInteractionContextWithDmAuth({
+      ctx: this.ctx,
+      interaction,
+      label: "agent select",
+      componentLabel: "select menu",
+      defer: false,
+    });
+    if (!interactionCtx) {
+      return;
+    }
+    const {
+      channelId,
+      user,
+      username,
+      userId,
+      replyOpts,
+      rawGuildId,
+      isDirectMessage,
+      isGroupDm,
+      memberRoleIds,
+    } = interactionCtx;
+
+    const allowed = await ensureAgentComponentInteractionAllowed({
+      ctx: this.ctx,
+      interaction,
+      channelId,
+      rawGuildId,
+      memberRoleIds,
+      user,
+      replyOpts,
+      componentLabel: "select",
+      unauthorizedReply: "You are not authorized to use this select menu.",
+    });
+    if (!allowed) {
+      return;
+    }
+    const { parentId } = allowed;
+
+    const values = interaction.values ?? [];
+    const valuesText = values.length > 0 ? ` (selected: ${values.join(", ")})` : "";
+
+    const route = resolveAgentComponentRoute({
+      ctx: this.ctx,
+      rawGuildId,
+      memberRoleIds,
+      isDirectMessage,
+      isGroupDm,
+      userId,
+      channelId,
+      parentId,
+    });
+
+    const eventText = `[Discord select menu: ${componentId} interacted by ${username} (${userId})${valuesText}]`;
+
+    logDebug(`agent select: enqueuing event for channel ${channelId}: ${eventText}`);
+
+    enqueueSystemEvent(eventText, {
+      sessionKey: route.sessionKey,
+      contextKey: `discord:agent-select:${channelId}:${componentId}:${userId}`,
+      forceSenderIsOwnerFalse: true,
+      trusted: false,
+    });
+
+    await ackComponentInteraction({ interaction, replyOpts, label: "agent select" });
+  }
+}
+
+export function createAgentComponentButton(ctx: AgentComponentContext): Button {
+  return new AgentComponentButton(ctx);
+}
+
+export function createAgentSelectMenu(ctx: AgentComponentContext): StringSelectMenu {
+  return new AgentSelectMenu(ctx);
+}

package/src/monitor/agent-components.ts

@@ -0,0 +1,70 @@
+import { Modal, type BaseMessageInteractiveComponent } from "../internal/discord.js";
+import type { AgentComponentContext } from "./agent-components-helpers.js";
+import { discordComponentControlHandlers } from "./agent-components.handlers.js";
+import { DiscordComponentModal } from "./agent-components.modal.js";
+import {
+  createAgentComponentButton,
+  createAgentSelectMenu,
+} from "./agent-components.system-controls.js";
+import {
+  createDiscordComponentButtonControl,
+  createDiscordComponentChannelSelectControl,
+  createDiscordComponentMentionableSelectControl,
+  createDiscordComponentRoleSelectControl,
+  createDiscordComponentStringSelectControl,
+  createDiscordComponentUserSelectControl,
+  type DiscordComponentControlHandlers,
+} from "./agent-components.wildcard-controls.js";
+
+export { resolveDiscordComponentOriginatingTo } from "./agent-components.dispatch.js";
+export {
+  AgentComponentButton,
+  AgentSelectMenu,
+  createAgentComponentButton,
+  createAgentSelectMenu,
+} from "./agent-components.system-controls.js";
+
+type ComponentFactory = (ctx: AgentComponentContext) => BaseMessageInteractiveComponent;
+
+function bindDiscordComponentControl<T extends BaseMessageInteractiveComponent>(
+  createControl: (ctx: AgentComponentContext, handlers: DiscordComponentControlHandlers) => T,
+) {
+  return (ctx: AgentComponentContext): T => createControl(ctx, discordComponentControlHandlers);
+}
+
+export const createDiscordComponentButton = bindDiscordComponentControl(
+  createDiscordComponentButtonControl,
+);
+export const createDiscordComponentStringSelect = bindDiscordComponentControl(
+  createDiscordComponentStringSelectControl,
+);
+export const createDiscordComponentUserSelect = bindDiscordComponentControl(
+  createDiscordComponentUserSelectControl,
+);
+export const createDiscordComponentRoleSelect = bindDiscordComponentControl(
+  createDiscordComponentRoleSelectControl,
+);
+export const createDiscordComponentMentionableSelect = bindDiscordComponentControl(
+  createDiscordComponentMentionableSelectControl,
+);
+export const createDiscordComponentChannelSelect = bindDiscordComponentControl(
+  createDiscordComponentChannelSelectControl,
+);
+
+export const createAgentComponentControls = [
+  createAgentComponentButton,
+  createAgentSelectMenu,
+] satisfies readonly ComponentFactory[];
+
+export const createDiscordComponentControls = [
+  createDiscordComponentButton,
+  createDiscordComponentStringSelect,
+  createDiscordComponentUserSelect,
+  createDiscordComponentRoleSelect,
+  createDiscordComponentMentionableSelect,
+  createDiscordComponentChannelSelect,
+] satisfies readonly ComponentFactory[];
+
+export function createDiscordComponentModal(ctx: AgentComponentContext): Modal {
+  return new DiscordComponentModal(ctx);
+}

package/src/monitor/agent-components.types.ts

@@ -0,0 +1,58 @@
+import type { DiscordAccountConfig, KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type {
+  ButtonInteraction,
+  ChannelSelectMenuInteraction,
+  MentionableSelectMenuInteraction,
+  ModalInteraction,
+  RoleSelectMenuInteraction,
+  StringSelectMenuInteraction,
+  UserSelectMenuInteraction,
+} from "../internal/discord.js";
+import type { DiscordGuildEntryResolved } from "./allow-list.js";
+import type { formatDiscordUserTag } from "./format.js";
+
+export type DiscordUser = Parameters<typeof formatDiscordUserTag>[0];
+
+export type AgentComponentMessageInteraction =
+  | ButtonInteraction
+  | StringSelectMenuInteraction
+  | RoleSelectMenuInteraction
+  | UserSelectMenuInteraction
+  | MentionableSelectMenuInteraction
+  | ChannelSelectMenuInteraction;
+
+export type AgentComponentInteraction = AgentComponentMessageInteraction | ModalInteraction;
+
+export type DiscordChannelContext = {
+  channelName: string | undefined;
+  channelSlug: string;
+  displayChannelSlug: string;
+  channelType: number | undefined;
+  isThread: boolean;
+  parentId: string | undefined;
+  parentName: string | undefined;
+  parentSlug: string;
+};
+
+export type AgentComponentContext = {
+  cfg: KlawConfig;
+  accountId: string;
+  discordConfig?: DiscordAccountConfig;
+  runtime?: import("klaw/plugin-sdk/runtime-env").RuntimeEnv;
+  token?: string;
+  guildEntries?: Record<string, DiscordGuildEntryResolved>;
+  allowFrom?: string[];
+  dmPolicy?: "open" | "pairing" | "allowlist" | "disabled";
+};
+
+export type ComponentInteractionContext = {
+  channelId: string;
+  user: DiscordUser;
+  username: string;
+  userId: string;
+  replyOpts: { ephemeral?: boolean };
+  rawGuildId: string | undefined;
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  memberRoleIds: string[];
+};