@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/dm-command-decision.test.ts

@@ -0,0 +1,108 @@
+import type { ResolvedChannelMessageIngress } from "klaw/plugin-sdk/channel-ingress-runtime";
+import { describe, expect, it, vi } from "vitest";
+import { handleDiscordDmCommandDecision } from "./dm-command-decision.js";
+
+function buildSenderAccess(
+  overrides: Pick<Partial<ResolvedChannelMessageIngress["senderAccess"]>, "decision">,
+): Pick<ResolvedChannelMessageIngress["senderAccess"], "decision"> {
+  return {
+    decision: "allow",
+    ...overrides,
+  };
+}
+
+const TEST_ACCOUNT_ID = "default";
+const TEST_SENDER = { id: "123", tag: "alice#0001", name: "alice" };
+
+function createDmDecisionHarness(params?: { pairingCreated?: boolean }) {
+  const onPairingCreated = vi.fn(async () => {});
+  const onUnauthorized = vi.fn(async () => {});
+  const upsertPairingRequest = vi.fn(async () => ({
+    code: "PAIR-1",
+    created: params?.pairingCreated ?? true,
+  }));
+  return { onPairingCreated, onUnauthorized, upsertPairingRequest };
+}
+
+async function runPairingDecision(params?: { pairingCreated?: boolean }) {
+  const harness = createDmDecisionHarness({ pairingCreated: params?.pairingCreated });
+  const allowed = await handleDiscordDmCommandDecision({
+    senderAccess: buildSenderAccess({
+      decision: "pairing",
+    }),
+    accountId: TEST_ACCOUNT_ID,
+    sender: TEST_SENDER,
+    onPairingCreated: harness.onPairingCreated,
+    onUnauthorized: harness.onUnauthorized,
+    upsertPairingRequest: harness.upsertPairingRequest,
+  });
+  return { allowed, ...harness };
+}
+
+describe("handleDiscordDmCommandDecision", () => {
+  it("returns true for allowed DM access", async () => {
+    const { onPairingCreated, onUnauthorized, upsertPairingRequest } = createDmDecisionHarness();
+
+    const allowed = await handleDiscordDmCommandDecision({
+      senderAccess: buildSenderAccess({ decision: "allow" }),
+      accountId: TEST_ACCOUNT_ID,
+      sender: TEST_SENDER,
+      onPairingCreated,
+      onUnauthorized,
+      upsertPairingRequest,
+    });
+
+    expect(allowed).toBe(true);
+    expect(upsertPairingRequest).not.toHaveBeenCalled();
+    expect(onPairingCreated).not.toHaveBeenCalled();
+    expect(onUnauthorized).not.toHaveBeenCalled();
+  });
+
+  it("creates pairing reply for new pairing requests", async () => {
+    const { allowed, onPairingCreated, onUnauthorized, upsertPairingRequest } =
+      await runPairingDecision();
+
+    expect(allowed).toBe(false);
+    expect(upsertPairingRequest).toHaveBeenCalledWith({
+      channel: "discord",
+      id: "123",
+      accountId: TEST_ACCOUNT_ID,
+      meta: {
+        tag: TEST_SENDER.tag,
+        name: TEST_SENDER.name,
+      },
+    });
+    expect(onPairingCreated).toHaveBeenCalledWith("PAIR-1");
+    expect(onUnauthorized).not.toHaveBeenCalled();
+  });
+
+  it("skips pairing reply when pairing request already exists", async () => {
+    const { allowed, onPairingCreated, onUnauthorized } = await runPairingDecision({
+      pairingCreated: false,
+    });
+
+    expect(allowed).toBe(false);
+    expect(onPairingCreated).not.toHaveBeenCalled();
+    expect(onUnauthorized).not.toHaveBeenCalled();
+  });
+
+  it("runs unauthorized handler for blocked DM access", async () => {
+    const { onPairingCreated, onUnauthorized, upsertPairingRequest } = createDmDecisionHarness();
+
+    const allowed = await handleDiscordDmCommandDecision({
+      senderAccess: buildSenderAccess({
+        decision: "block",
+      }),
+      accountId: TEST_ACCOUNT_ID,
+      sender: TEST_SENDER,
+      onPairingCreated,
+      onUnauthorized,
+      upsertPairingRequest,
+    });
+
+    expect(allowed).toBe(false);
+    expect(onUnauthorized).toHaveBeenCalledTimes(1);
+    expect(upsertPairingRequest).not.toHaveBeenCalled();
+    expect(onPairingCreated).not.toHaveBeenCalled();
+  });
+});

package/src/monitor/dm-command-decision.ts

@@ -0,0 +1,49 @@
+import type { ResolvedChannelMessageIngress } from "klaw/plugin-sdk/channel-ingress-runtime";
+import { createChannelPairingChallengeIssuer } from "klaw/plugin-sdk/channel-pairing";
+import { upsertChannelPairingRequest } from "klaw/plugin-sdk/conversation-runtime";
+
+export async function handleDiscordDmCommandDecision(params: {
+  senderAccess: Pick<ResolvedChannelMessageIngress["senderAccess"], "decision">;
+  accountId: string;
+  sender: {
+    id: string;
+    tag?: string;
+    name?: string;
+  };
+  onPairingCreated: (code: string) => Promise<void>;
+  onUnauthorized: () => Promise<void>;
+  upsertPairingRequest?: typeof upsertChannelPairingRequest;
+}): Promise<boolean> {
+  if (params.senderAccess.decision === "allow") {
+    return true;
+  }
+
+  if (params.senderAccess.decision === "pairing") {
+    const upsertPairingRequest = params.upsertPairingRequest ?? upsertChannelPairingRequest;
+    const result = await createChannelPairingChallengeIssuer({
+      channel: "discord",
+      upsertPairingRequest: async ({ id, meta }) =>
+        await upsertPairingRequest({
+          channel: "discord",
+          id,
+          accountId: params.accountId,
+          meta,
+        }),
+    })({
+      senderId: params.sender.id,
+      senderIdLine: `Your Discord user id: ${params.sender.id}`,
+      meta: {
+        tag: params.sender.tag,
+        name: params.sender.name,
+      },
+      sendPairingReply: async () => {},
+    });
+    if (result.created && result.code) {
+      await params.onPairingCreated(result.code);
+    }
+    return false;
+  }
+
+  await params.onUnauthorized();
+  return false;
+}

package/src/monitor/exec-approvals.test.ts

@@ -0,0 +1,225 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ButtonInteraction, ComponentData } from "../internal/discord.js";
+
+const resolveApprovalOverGatewayMock = vi.hoisted(() => vi.fn());
+
+vi.mock("klaw/plugin-sdk/approval-gateway-runtime", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("klaw/plugin-sdk/approval-gateway-runtime")>();
+  return {
+    ...actual,
+    resolveApprovalOverGateway: resolveApprovalOverGatewayMock,
+  };
+});
+
+import {
+  ExecApprovalButton,
+  buildExecApprovalCustomId,
+  createDiscordExecApprovalButtonContext,
+  extractDiscordChannelId,
+  parseExecApprovalData,
+} from "./exec-approvals.js";
+
+function buildConfig(
+  execApprovals?: NonNullable<NonNullable<KlawConfig["channels"]>["discord"]>["execApprovals"],
+): KlawConfig {
+  return {
+    channels: {
+      discord: {
+        token: "discord-token",
+        execApprovals,
+      },
+    },
+  } as KlawConfig;
+}
+
+function createInteraction(overrides?: Partial<ButtonInteraction>): ButtonInteraction {
+  return {
+    userId: "123",
+    reply: vi.fn(),
+    acknowledge: vi.fn(),
+    followUp: vi.fn(),
+    ...overrides,
+  } as unknown as ButtonInteraction;
+}
+
+describe("discord exec approval monitor helpers", () => {
+  beforeEach(() => {
+    resolveApprovalOverGatewayMock.mockReset();
+  });
+
+  it("encodes approval ids into custom ids", () => {
+    expect(buildExecApprovalCustomId("abc-123", "allow-once")).toBe(
+      "execapproval:id=abc-123;action=allow-once",
+    );
+    expect(buildExecApprovalCustomId("abc=123;test", "deny")).toBe(
+      "execapproval:id=abc%3D123%3Btest;action=deny",
+    );
+  });
+
+  it("parses valid button data and rejects invalid payloads", () => {
+    expect(parseExecApprovalData({ id: "abc-123", action: "allow-once" })).toEqual({
+      approvalId: "abc-123",
+      action: "allow-once",
+    });
+    expect(
+      parseExecApprovalData({
+        id: "abc%3D123%3Btest",
+        action: "allow-always",
+      }),
+    ).toEqual({
+      approvalId: "abc=123;test",
+      action: "allow-always",
+    });
+    expect(parseExecApprovalData({ id: "abc", action: "invalid" })).toBeNull();
+    expect(parseExecApprovalData({ action: "deny" } as ComponentData)).toBeNull();
+  });
+
+  it("extracts discord channel ids from session keys", () => {
+    expect(extractDiscordChannelId("agent:main:discord:channel:123456789")).toBe("123456789");
+    expect(extractDiscordChannelId("agent:main:discord:group:222333444")).toBe("222333444");
+    expect(extractDiscordChannelId("agent:main:telegram:channel:123456789")).toBeNull();
+    expect(extractDiscordChannelId("")).toBeNull();
+  });
+
+  it("rejects invalid approval button payloads", async () => {
+    const interaction = createInteraction();
+    const button = new ExecApprovalButton({
+      getApprovers: () => ["123"],
+      resolveApproval: async () => ({ ok: true }),
+    });
+
+    await button.run(interaction, { id: "", action: "" });
+
+    expect(interaction.reply).toHaveBeenCalledWith({
+      content: "This approval is no longer valid.",
+      ephemeral: true,
+    });
+  });
+
+  it("blocks non-approvers from approving", async () => {
+    const interaction = createInteraction({ userId: "999" });
+    const button = new ExecApprovalButton({
+      getApprovers: () => ["123"],
+      resolveApproval: async () => ({ ok: true }),
+    });
+
+    await button.run(interaction, { id: "abc", action: "allow-once" });
+
+    expect(interaction.reply).toHaveBeenCalledWith({
+      content: "⛔ You are not authorized to approve exec requests.",
+      ephemeral: true,
+    });
+  });
+
+  it("acknowledges and resolves valid approval clicks", async () => {
+    const interaction = createInteraction();
+    const resolveApproval = vi.fn(async () => ({ ok: true }) as const);
+    const button = new ExecApprovalButton({
+      getApprovers: () => ["123"],
+      resolveApproval,
+    });
+
+    await button.run(interaction, { id: "abc", action: "allow-once" });
+
+    expect(interaction.acknowledge).toHaveBeenCalled();
+    expect(resolveApproval).toHaveBeenCalledWith("abc", "allow-once");
+    expect(interaction.followUp).not.toHaveBeenCalled();
+  });
+
+  it("shows a follow-up when gateway resolution fails", async () => {
+    const interaction = createInteraction();
+    const button = new ExecApprovalButton({
+      getApprovers: () => ["123"],
+      resolveApproval: async () => ({ ok: false, reason: "error" }),
+    });
+
+    await button.run(interaction, { id: "abc", action: "deny" });
+
+    expect(interaction.followUp).toHaveBeenCalledWith({
+      content:
+        "Failed to submit approval decision for **Denied**. The request may have expired or already been resolved.",
+      ephemeral: true,
+    });
+  });
+
+  it("keeps already-resolved approval clicks quiet", async () => {
+    const interaction = createInteraction();
+    const button = new ExecApprovalButton({
+      getApprovers: () => ["123"],
+      resolveApproval: async () => ({ ok: false, reason: "not-found" }),
+    });
+
+    await button.run(interaction, { id: "abc", action: "allow-once" });
+
+    expect(interaction.acknowledge).toHaveBeenCalled();
+    expect(interaction.followUp).not.toHaveBeenCalled();
+  });
+
+  it("builds button context from config and routes resolution over gateway", async () => {
+    const cfg = buildConfig({ enabled: true, approvers: ["123"] });
+    resolveApprovalOverGatewayMock.mockResolvedValue(undefined);
+    const ctx = createDiscordExecApprovalButtonContext({
+      cfg,
+      accountId: "default",
+      config: { enabled: true, approvers: ["123"] },
+      gatewayUrl: "ws://127.0.0.1:18789",
+    });
+
+    expect(ctx.getApprovers()).toEqual(["123"]);
+    await expect(ctx.resolveApproval("abc", "allow-once")).resolves.toEqual({ ok: true });
+    expect(resolveApprovalOverGatewayMock).toHaveBeenCalledWith({
+      cfg,
+      approvalId: "abc",
+      decision: "allow-once",
+      gatewayUrl: "ws://127.0.0.1:18789",
+      clientDisplayName: "Discord approval (default)",
+    });
+  });
+
+  it("returns false when gateway resolution throws", async () => {
+    resolveApprovalOverGatewayMock.mockRejectedValue(new Error("boom"));
+    const ctx = createDiscordExecApprovalButtonContext({
+      cfg: buildConfig({ enabled: true, approvers: ["123"] }),
+      accountId: "default",
+      config: { enabled: true, approvers: ["123"] },
+    });
+
+    await expect(ctx.resolveApproval("abc", "allow-once")).resolves.toEqual({
+      ok: false,
+      reason: "error",
+    });
+  });
+
+  it("classifies structured approval-not-found gateway errors as stale clicks", async () => {
+    const err = Object.assign(new Error("unknown or expired approval id"), {
+      gatewayCode: "INVALID_REQUEST",
+      details: { reason: "APPROVAL_NOT_FOUND" },
+    });
+    resolveApprovalOverGatewayMock.mockRejectedValue(err);
+    const ctx = createDiscordExecApprovalButtonContext({
+      cfg: buildConfig({ enabled: true, approvers: ["123"] }),
+      accountId: "default",
+      config: { enabled: true, approvers: ["123"] },
+    });
+
+    await expect(ctx.resolveApproval("abc", "allow-once")).resolves.toEqual({
+      ok: false,
+      reason: "not-found",
+    });
+  });
+
+  it("keeps message-only approval-not-found errors visible", async () => {
+    resolveApprovalOverGatewayMock.mockRejectedValue(new Error("unknown or expired approval id"));
+    const ctx = createDiscordExecApprovalButtonContext({
+      cfg: buildConfig({ enabled: true, approvers: ["123"] }),
+      accountId: "default",
+      config: { enabled: true, approvers: ["123"] },
+    });
+
+    await expect(ctx.resolveApproval("abc", "allow-once")).resolves.toEqual({
+      ok: false,
+      reason: "error",
+    });
+  });
+});

package/src/monitor/exec-approvals.ts

@@ -0,0 +1,158 @@
+import { ButtonStyle } from "discord-api-types/v10";
+import { resolveApprovalOverGateway } from "klaw/plugin-sdk/approval-gateway-runtime";
+import type { ExecApprovalDecision } from "klaw/plugin-sdk/approval-runtime";
+import type { DiscordExecApprovalConfig, KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { Button, type ButtonInteraction, type ComponentData } from "../internal/discord.js";
+export { buildExecApprovalCustomId } from "../approval-handler.runtime.js";
+import { getDiscordExecApprovalApprovers } from "../exec-approvals.js";
+
+export { extractDiscordChannelId } from "../approval-native.js";
+function decodeCustomIdValue(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export function parseExecApprovalData(
+  data: ComponentData,
+): { approvalId: string; action: ExecApprovalDecision } | null {
+  if (!data || typeof data !== "object") {
+    return null;
+  }
+  const coerce = (value: unknown) =>
+    typeof value === "string" || typeof value === "number" ? String(value) : "";
+  const rawId = coerce(data.id);
+  const rawAction = coerce(data.action);
+  if (!rawId || !rawAction) {
+    return null;
+  }
+  const action = rawAction as ExecApprovalDecision;
+  if (action !== "allow-once" && action !== "allow-always" && action !== "deny") {
+    return null;
+  }
+  return {
+    approvalId: decodeCustomIdValue(rawId),
+    action,
+  };
+}
+
+type ExecApprovalButtonContext = {
+  getApprovers: () => string[];
+  resolveApproval: (
+    approvalId: string,
+    decision: ExecApprovalDecision,
+  ) => Promise<ExecApprovalResolveResult>;
+};
+
+type ExecApprovalResolveResult = { ok: true } | { ok: false; reason: "error" | "not-found" };
+
+function isStructuredApprovalNotFoundError(err: unknown): boolean {
+  if (!err || typeof err !== "object") {
+    return false;
+  }
+  const record = err as {
+    gatewayCode?: unknown;
+    details?: { reason?: unknown } | null;
+  };
+  if (record.gatewayCode === "APPROVAL_NOT_FOUND") {
+    return true;
+  }
+  return (
+    record.gatewayCode === "INVALID_REQUEST" && record.details?.reason === "APPROVAL_NOT_FOUND"
+  );
+}
+
+export class ExecApprovalButton extends Button {
+  override label = "execapproval";
+  customId = "execapproval:seed=1";
+  override style = ButtonStyle.Primary;
+
+  constructor(private readonly ctx: ExecApprovalButtonContext) {
+    super();
+  }
+
+  override async run(interaction: ButtonInteraction, data: ComponentData): Promise<void> {
+    const parsed = parseExecApprovalData(data);
+    if (!parsed) {
+      try {
+        await interaction.reply({
+          content: "This approval is no longer valid.",
+          ephemeral: true,
+        });
+      } catch {}
+      return;
+    }
+
+    const approvers = this.ctx.getApprovers();
+    const userId = interaction.userId;
+    if (!approvers.some((id) => id === userId)) {
+      try {
+        await interaction.reply({
+          content: "⛔ You are not authorized to approve exec requests.",
+          ephemeral: true,
+        });
+      } catch {}
+      return;
+    }
+
+    const decisionLabel =
+      parsed.action === "allow-once"
+        ? "Allowed (once)"
+        : parsed.action === "allow-always"
+          ? "Allowed (always)"
+          : "Denied";
+
+    try {
+      await interaction.acknowledge();
+    } catch {}
+
+    const result = await this.ctx.resolveApproval(parsed.approvalId, parsed.action);
+    if (!result.ok && result.reason !== "not-found") {
+      try {
+        await interaction.followUp({
+          content: `Failed to submit approval decision for **${decisionLabel}**. The request may have expired or already been resolved.`,
+          ephemeral: true,
+        });
+      } catch {}
+    }
+  }
+}
+
+export function createExecApprovalButton(ctx: ExecApprovalButtonContext): Button {
+  return new ExecApprovalButton(ctx);
+}
+
+export function createDiscordExecApprovalButtonContext(params: {
+  cfg: KlawConfig;
+  accountId: string;
+  config: DiscordExecApprovalConfig;
+  gatewayUrl?: string;
+}): ExecApprovalButtonContext {
+  return {
+    getApprovers: () =>
+      getDiscordExecApprovalApprovers({
+        cfg: params.cfg,
+        accountId: params.accountId,
+        configOverride: params.config,
+      }),
+    resolveApproval: async (approvalId, decision) => {
+      try {
+        await resolveApprovalOverGateway({
+          cfg: params.cfg,
+          approvalId,
+          decision,
+          gatewayUrl: params.gatewayUrl,
+          clientDisplayName: `Discord approval (${params.accountId})`,
+        });
+        return { ok: true };
+      } catch (err) {
+        return {
+          ok: false,
+          reason: isStructuredApprovalNotFoundError(err) ? "not-found" : "error",
+        };
+      }
+    },
+  };
+}

package/src/monitor/format.ts

@@ -0,0 +1,45 @@
+import type { Guild, User } from "../internal/discord.js";
+
+export function resolveDiscordSystemLocation(params: {
+  isDirectMessage: boolean;
+  isGroupDm: boolean;
+  guild?: Guild;
+  channelName: string;
+}) {
+  const { isDirectMessage, isGroupDm, guild, channelName } = params;
+  if (isDirectMessage) {
+    return "DM";
+  }
+  if (isGroupDm) {
+    return `Group DM #${channelName}`;
+  }
+  return guild?.name ? `${guild.name} #${channelName}` : `#${channelName}`;
+}
+
+export function formatDiscordReactionEmoji(emoji: { id?: string | null; name?: string | null }) {
+  if (emoji.id && emoji.name) {
+    // Custom guild emoji in Discord-renderable form.
+    return `<:${emoji.name}:${emoji.id}>`;
+  }
+  if (emoji.id) {
+    // Keep id visible even when name is missing (instead of opaque "emoji").
+    return `emoji:${emoji.id}`;
+  }
+  return emoji.name ?? "emoji";
+}
+
+export function formatDiscordUserTag(user: User) {
+  const discriminator = (user.discriminator ?? "").trim();
+  if (discriminator && discriminator !== "0") {
+    return `${user.username}#${discriminator}`;
+  }
+  return user.username ?? user.id;
+}
+
+export function resolveTimestampMs(timestamp?: string | null) {
+  if (!timestamp) {
+    return undefined;
+  }
+  const parsed = Date.parse(timestamp);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}

package/src/monitor/gateway-handle.ts

@@ -0,0 +1,33 @@
+import type { EventEmitter } from "node:events";
+import type { GatewayPlugin } from "../internal/gateway.js";
+
+export const DISCORD_GATEWAY_TRANSPORT_ACTIVITY_EVENT = "klaw:discord-gateway-transport-activity";
+
+export type DiscordGatewayHandle = Pick<GatewayPlugin, "disconnect"> & {
+  emitter?: EventEmitter;
+};
+
+type GatewaySocketListener = (...args: unknown[]) => void;
+
+type DiscordGatewaySocket = {
+  on: (event: "close" | "error", listener: GatewaySocketListener) => unknown;
+  listeners: (event: "close" | "error") => GatewaySocketListener[];
+  removeListener: (event: "close" | "error", listener: GatewaySocketListener) => unknown;
+  terminate?: () => void;
+};
+
+export type MutableDiscordGateway = GatewayPlugin & {
+  emitter?: EventEmitter;
+  options: Record<string, unknown> & {
+    reconnect?: {
+      maxAttempts?: number;
+    };
+  };
+  state?: {
+    sessionId?: string | null;
+    resumeGatewayUrl?: string | null;
+    sequence?: number | null;
+  };
+  sequence?: number | null;
+  ws?: DiscordGatewaySocket | null;
+};

package/src/monitor/gateway-metadata.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from "vitest";
+import { fetchDiscordGatewayInfo, resolveGatewayInfoWithFallback } from "./gateway-metadata.js";
+
+describe("Discord gateway metadata", () => {
+  it("falls back on Cloudflare HTML rate limits without logging raw HTML", async () => {
+    const error = await fetchDiscordGatewayInfo({
+      token: "test",
+      fetchImpl: async () =>
+        new Response("<html><title>Error 1015</title><body>rate limited</body></html>", {
+          status: 429,
+          headers: { "content-type": "text/html" },
+        }),
+    }).catch((err: unknown) => err);
+    const runtime = {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: vi.fn(),
+    };
+
+    const resolved = resolveGatewayInfoWithFallback({ runtime, error });
+
+    expect(resolved.usedFallback).toBe(true);
+    expect(resolved.info.url).toBe("wss://gateway.discord.gg/");
+    const logs = runtime.log.mock.calls.map((call) => String(call[0])).join("\n");
+    expect(logs).toBe(
+      "discord: gateway metadata lookup failed transiently; using default gateway url (Failed to get gateway information from Discord: fetch failed | Discord API /gateway/bot failed (429): Error 1015 rate limited)",
+    );
+  });
+});