@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/reply-delivery.ts

@@ -0,0 +1,212 @@
+import { resolveAgentAvatar } from "klaw/plugin-sdk/agent-runtime";
+import { sendDurableMessageBatch } from "klaw/plugin-sdk/channel-message";
+import type { MarkdownTableMode, KlawConfig, ReplyToMode } from "klaw/plugin-sdk/config-contracts";
+import type { OutboundMediaAccess } from "klaw/plugin-sdk/media-runtime";
+import {
+  buildOutboundSessionContext,
+  type OutboundDeliveryFormattingOptions,
+  type OutboundIdentity,
+  type OutboundSendDeps,
+} from "klaw/plugin-sdk/outbound-runtime";
+import type { ChunkMode } from "klaw/plugin-sdk/reply-chunking";
+import type { ReplyPayload } from "klaw/plugin-sdk/reply-dispatch-runtime";
+import type { RuntimeEnv } from "klaw/plugin-sdk/runtime-env";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import type { RequestClient } from "../internal/discord.js";
+import { sendMessageDiscord, sendVoiceMessageDiscord } from "../send.js";
+import { sanitizeDiscordFrontChannelReplyPayloads } from "./reply-safety.js";
+
+export type DiscordThreadBindingLookupRecord = {
+  accountId: string;
+  channelId: string;
+  threadId: string;
+  agentId: string;
+  label?: string;
+  webhookId?: string;
+  webhookToken?: string;
+};
+
+export type DiscordThreadBindingLookup = {
+  listBySessionKey: (targetSessionKey: string) => DiscordThreadBindingLookupRecord[];
+  touchThread?: (params: { threadId: string; at?: number; persist?: boolean }) => unknown;
+};
+
+function resolveTargetChannelId(target: string): string | undefined {
+  if (!target.startsWith("channel:")) {
+    return undefined;
+  }
+  const channelId = target.slice("channel:".length).trim();
+  return channelId || undefined;
+}
+
+function resolveBoundThreadBinding(params: {
+  threadBindings?: DiscordThreadBindingLookup;
+  sessionKey?: string;
+  target: string;
+}): DiscordThreadBindingLookupRecord | undefined {
+  const sessionKey = params.sessionKey?.trim();
+  if (!params.threadBindings || !sessionKey) {
+    return undefined;
+  }
+  const targetChannelId = resolveTargetChannelId(params.target);
+  if (!targetChannelId) {
+    return undefined;
+  }
+  return params.threadBindings
+    .listBySessionKey(sessionKey)
+    .find((entry) => entry.threadId === targetChannelId);
+}
+
+function resolveBindingIdentity(
+  cfg: KlawConfig,
+  binding: DiscordThreadBindingLookupRecord | undefined,
+): OutboundIdentity | undefined {
+  if (!binding) {
+    return undefined;
+  }
+  const baseLabel = binding.label?.trim() || binding.agentId;
+  const identity: OutboundIdentity = {
+    name: (`🤖 ${baseLabel}`.trim() || "🤖 agent").slice(0, 80),
+  };
+  try {
+    const avatar = resolveAgentAvatar(cfg, binding.agentId);
+    if (avatar.kind === "remote") {
+      identity.avatarUrl = avatar.url;
+    }
+  } catch {
+    // Avatar is cosmetic; delivery should not depend on local identity config.
+  }
+  return identity;
+}
+
+function createDiscordDeliveryDeps(params: {
+  cfg: KlawConfig;
+  token: string;
+  rest?: RequestClient;
+}): OutboundSendDeps {
+  return {
+    discord: (to: string, text: string, opts?: Parameters<typeof sendMessageDiscord>[2]) =>
+      sendMessageDiscord(to, text, {
+        ...opts,
+        cfg: opts?.cfg ?? params.cfg,
+        token: params.token,
+        rest: params.rest,
+      }),
+    discordVoice: (
+      to: string,
+      audioPath: string,
+      opts?: Parameters<typeof sendVoiceMessageDiscord>[2],
+    ) =>
+      sendVoiceMessageDiscord(to, audioPath, {
+        ...opts,
+        cfg: opts?.cfg ?? params.cfg,
+        token: params.token,
+        rest: params.rest,
+      }),
+  };
+}
+
+type DiscordDeliveryOptions = {
+  to: string;
+  threadId?: string;
+  agentId?: string;
+  identity?: OutboundIdentity;
+  mediaAccess?: OutboundMediaAccess;
+  replyToMode: ReplyToMode;
+  formatting: OutboundDeliveryFormattingOptions;
+};
+
+function resolveDiscordDeliveryOptions(params: {
+  cfg: KlawConfig;
+  target: string;
+  sessionKey?: string;
+  threadBindings?: DiscordThreadBindingLookup;
+  textLimit: number;
+  maxLinesPerMessage?: number;
+  tableMode?: MarkdownTableMode;
+  chunkMode?: ChunkMode;
+  replyToMode?: ReplyToMode;
+  mediaLocalRoots?: readonly string[];
+}): DiscordDeliveryOptions {
+  const binding = resolveBoundThreadBinding({
+    threadBindings: params.threadBindings,
+    sessionKey: params.sessionKey,
+    target: params.target,
+  });
+  return {
+    to: binding ? `channel:${binding.channelId}` : params.target,
+    threadId: binding?.threadId,
+    agentId: binding?.agentId,
+    identity: resolveBindingIdentity(params.cfg, binding),
+    mediaAccess: params.mediaLocalRoots?.length
+      ? { localRoots: params.mediaLocalRoots }
+      : undefined,
+    replyToMode: params.replyToMode ?? "all",
+    formatting: {
+      textLimit: params.textLimit,
+      maxLinesPerMessage: params.maxLinesPerMessage,
+      tableMode: params.tableMode,
+      chunkMode: params.chunkMode,
+    },
+  };
+}
+
+export async function deliverDiscordReply(params: {
+  cfg: KlawConfig;
+  replies: ReplyPayload[];
+  target: string;
+  token: string;
+  accountId?: string;
+  rest?: RequestClient;
+  runtime: RuntimeEnv;
+  textLimit: number;
+  maxLinesPerMessage?: number;
+  replyToId?: string;
+  replyToMode?: ReplyToMode;
+  tableMode?: MarkdownTableMode;
+  chunkMode?: ChunkMode;
+  sessionKey?: string;
+  threadBindings?: DiscordThreadBindingLookup;
+  mediaLocalRoots?: readonly string[];
+  kind: "tool" | "block" | "final";
+}) {
+  void params.runtime;
+
+  const delivery = resolveDiscordDeliveryOptions(params);
+  const payloads = sanitizeDiscordFrontChannelReplyPayloads(params.replies, { kind: params.kind });
+  if (payloads.length === 0) {
+    return;
+  }
+
+  const send = await sendDurableMessageBatch({
+    cfg: params.cfg,
+    channel: "discord",
+    to: delivery.to,
+    accountId: params.accountId,
+    payloads,
+    replyToId: normalizeOptionalString(params.replyToId),
+    replyToMode: delivery.replyToMode,
+    formatting: delivery.formatting,
+    threadId: delivery.threadId,
+    identity: delivery.identity,
+    deps: createDiscordDeliveryDeps({
+      cfg: params.cfg,
+      token: params.token,
+      rest: params.rest,
+    }),
+    mediaAccess: delivery.mediaAccess,
+    session: buildOutboundSessionContext({
+      cfg: params.cfg,
+      sessionKey: params.sessionKey,
+      agentId: delivery.agentId,
+      requesterAccountId: params.accountId,
+    }),
+  });
+  if (send.status === "failed" || send.status === "partial_failed") {
+    throw send.error;
+  }
+  const results = send.status === "sent" ? send.results : [];
+  if (results.length === 0) {
+    throw new Error(`discord final reply produced no delivered message for ${delivery.to}`);
+  }
+}

package/src/monitor/reply-safety.ts

@@ -0,0 +1,96 @@
+import type { ReplyPayload } from "klaw/plugin-sdk/reply-dispatch-runtime";
+import { resolveSendableOutboundReplyParts } from "klaw/plugin-sdk/reply-payload";
+import { sanitizeAssistantVisibleText } from "klaw/plugin-sdk/text-chunking";
+
+const DISCORD_INTERNAL_TRACE_LINE_RE =
+  /^(?:>\s*)?(?:📊|🛠️|📖|📝|🔍|🔎|⚙️)\s*(?:Session Status|Exec|Read|Edit|Write|Patch|Search|Open|Click|Find|Screenshot|Update Plan|Tool Call|Tool Result|Function Call|Shell|Command)\s*:/i;
+const DISCORD_INTERNAL_COMPACT_COMMAND_TRACE_LINE_RE =
+  /^(?:>\s*)?🛠️\s*(?:(?:(?:elevated|pty)\b\s*(?:·|,)\s*)+)?(?:`{1,2}\s*\S|(?:run|check|fetch|pull|push|view|show|list|switch|create|merge|rebase|stage|restore|reset|stash|search|find|print|copy|move|remove|install|start|cd|git|pnpm|npm|yarn|bun|node|python|python3|bash|sh)\b)/i;
+const DISCORD_INTERNAL_CHANNEL_LINE_RE =
+  /^(?:>\s*)?(?:analysis|commentary|tool[-_ ]?call|tool[-_ ]?result|function[-_ ]?call|thinking|reasoning)\s*[:=]/i;
+
+function hasNonEmptyRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(
+    value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0,
+  );
+}
+
+function hasInteractiveOrPresentationBlocks(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.title === "string" && record.title.trim().length > 0) {
+    return true;
+  }
+  return Array.isArray(record.blocks) && record.blocks.length > 0;
+}
+
+function hasNonTextReplyPayloadContent(payload: ReplyPayload): boolean {
+  return (
+    payload.audioAsVoice === true ||
+    hasNonEmptyRecord(payload.channelData) ||
+    hasInteractiveOrPresentationBlocks(payload.interactive) ||
+    hasInteractiveOrPresentationBlocks(payload.presentation)
+  );
+}
+
+function stripDiscordInternalTraceLines(text: string): string {
+  let inFence = false;
+  const kept: string[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (/^\s*```/.test(line)) {
+      inFence = !inFence;
+      kept.push(line);
+      continue;
+    }
+    if (!inFence) {
+      const trimmed = line.trim();
+      if (
+        DISCORD_INTERNAL_TRACE_LINE_RE.test(trimmed) ||
+        DISCORD_INTERNAL_COMPACT_COMMAND_TRACE_LINE_RE.test(trimmed) ||
+        DISCORD_INTERNAL_CHANNEL_LINE_RE.test(trimmed)
+      ) {
+        continue;
+      }
+    }
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+function collapseExcessBlankLines(text: string): string {
+  return text.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n");
+}
+
+export function sanitizeDiscordFrontChannelText(text: string): string {
+  const withoutAssistantScaffolding = sanitizeAssistantVisibleText(text);
+  const withoutTraceLines = stripDiscordInternalTraceLines(withoutAssistantScaffolding);
+  return collapseExcessBlankLines(withoutTraceLines).trim();
+}
+
+export function sanitizeDiscordFrontChannelReplyPayloads(
+  payloads: readonly ReplyPayload[],
+  options: { kind?: "tool" | "block" | "final" } = {},
+): ReplyPayload[] {
+  const preserveVerboseToolProgress = options.kind === "tool";
+  const safePayloads: ReplyPayload[] = [];
+  for (const payload of payloads) {
+    const safeText =
+      typeof payload.text === "string"
+        ? preserveVerboseToolProgress
+          ? collapseExcessBlankLines(sanitizeAssistantVisibleText(payload.text)).trim()
+          : sanitizeDiscordFrontChannelText(payload.text)
+        : payload.text;
+    const nextPayload =
+      safeText === payload.text
+        ? payload
+        : ({ ...payload, text: safeText || undefined } as ReplyPayload);
+    const nextParts = resolveSendableOutboundReplyParts(nextPayload);
+    if (!nextParts.hasContent && !hasNonTextReplyPayloadContent(nextPayload)) {
+      continue;
+    }
+    safePayloads.push(nextPayload);
+  }
+  return safePayloads;
+}

package/src/monitor/rest-fetch.ts

@@ -0,0 +1,94 @@
+import { randomUUID } from "node:crypto";
+import { formatErrorMessage } from "klaw/plugin-sdk/error-runtime";
+import {
+  createHttp1EnvHttpProxyAgent,
+  createHttp1ProxyAgent,
+  resolveEnvHttpProxyAgentOptions,
+  wrapFetchWithAbortSignal,
+} from "klaw/plugin-sdk/fetch-runtime";
+import { captureHttpExchange, resolveEffectiveDebugProxyUrl } from "klaw/plugin-sdk/proxy-capture";
+import { resolveRequestUrl } from "klaw/plugin-sdk/request-url";
+import { danger } from "klaw/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "klaw/plugin-sdk/runtime-env";
+import { Agent, fetch as undiciFetch } from "undici";
+import { createDiscordDnsLookup } from "../network-config.js";
+import { withValidatedDiscordProxy } from "../proxy-fetch.js";
+
+const discordDnsLookup = createDiscordDnsLookup();
+
+type DiscordRestDispatcher =
+  | InstanceType<typeof Agent>
+  | ReturnType<typeof createHttp1EnvHttpProxyAgent>
+  | ReturnType<typeof createHttp1ProxyAgent>;
+
+function createDirectDiscordRestDispatcher(): InstanceType<typeof Agent> {
+  return new Agent({
+    allowH2: false,
+    connect: { lookup: discordDnsLookup },
+  });
+}
+
+function createEnvProxyDiscordRestDispatcher(
+  runtime: RuntimeEnv,
+): ReturnType<typeof createHttp1EnvHttpProxyAgent> | undefined {
+  const envProxyOptions = resolveEnvHttpProxyAgentOptions();
+  if (!envProxyOptions) {
+    return undefined;
+  }
+  try {
+    return createHttp1EnvHttpProxyAgent({
+      ...envProxyOptions,
+      connect: { lookup: discordDnsLookup },
+    });
+  } catch (err) {
+    runtime.error?.(
+      danger(
+        `discord: env proxy unavailable for REST fetch; using direct dispatcher: ${formatErrorMessage(err)}`,
+      ),
+    );
+    return undefined;
+  }
+}
+
+function createDiscordRestFetchWithDispatcher(dispatcher: DiscordRestDispatcher): typeof fetch {
+  return wrapFetchWithAbortSignal(((input: RequestInfo | URL, init?: RequestInit) =>
+    (
+      undiciFetch(input as string | URL, {
+        ...(init as Record<string, unknown>),
+        dispatcher,
+      }) as unknown as Promise<Response>
+    ).then((response) => {
+      captureHttpExchange({
+        url: resolveRequestUrl(input),
+        method: init?.method ?? "GET",
+        requestHeaders: init?.headers as Headers | Record<string, string> | undefined,
+        requestBody: (init as RequestInit & { body?: BodyInit | null })?.body ?? null,
+        response,
+        flowId: randomUUID(),
+        meta: { subsystem: "discord-rest" },
+      });
+      return response;
+    })) as typeof fetch);
+}
+
+export function resolveDiscordRestFetch(
+  proxyUrl: string | undefined,
+  runtime: RuntimeEnv,
+): typeof fetch {
+  const effectiveProxyUrl = resolveEffectiveDebugProxyUrl(proxyUrl);
+  if (effectiveProxyUrl) {
+    const fetcher = withValidatedDiscordProxy(effectiveProxyUrl, runtime, (proxy) =>
+      createDiscordRestFetchWithDispatcher(createHttp1ProxyAgent({ uri: proxy })),
+    );
+    if (!fetcher) {
+      return fetch;
+    }
+    runtime.log?.("discord: rest proxy enabled");
+    return fetcher;
+  }
+
+  const fetcher = createDiscordRestFetchWithDispatcher(
+    createEnvProxyDiscordRestDispatcher(runtime) ?? createDirectDiscordRestDispatcher(),
+  );
+  return fetcher;
+}

package/src/monitor/route-resolution.test.ts

@@ -0,0 +1,209 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { ResolvedAgentRoute } from "klaw/plugin-sdk/routing";
+import { describe, expect, it } from "vitest";
+import {
+  buildDiscordRoutePeer,
+  resolveDiscordBoundConversationRoute,
+  resolveDiscordConversationRoute,
+  resolveDiscordEffectiveRoute,
+  shouldIgnoreStaleDiscordRouteBinding,
+} from "./route-resolution.js";
+
+function buildWorkerBindingConfig(peer: { kind: "channel" | "direct"; id: string }): KlawConfig {
+  return {
+    agents: {
+      list: [{ id: "worker" }],
+    },
+    bindings: [
+      {
+        agentId: "worker",
+        match: {
+          channel: "discord",
+          accountId: "default",
+          peer,
+        },
+      },
+    ],
+  };
+}
+
+describe("discord route resolution helpers", () => {
+  it("builds a direct peer from DM metadata", () => {
+    expect(
+      buildDiscordRoutePeer({
+        isDirectMessage: true,
+        isGroupDm: false,
+        directUserId: "user-1",
+        conversationId: "channel-1",
+      }),
+    ).toEqual({
+      kind: "direct",
+      id: "user-1",
+    });
+  });
+
+  it("resolves bound session keys on top of the routed session", () => {
+    const route: ResolvedAgentRoute = {
+      agentId: "main",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:main:discord:channel:c1",
+      mainSessionKey: "agent:main:main",
+      lastRoutePolicy: "session",
+      matchedBy: "default",
+    };
+
+    expect(
+      resolveDiscordEffectiveRoute({
+        route,
+        boundSessionKey: "agent:worker:discord:channel:c1",
+        matchedBy: "binding.channel",
+      }),
+    ).toEqual({
+      ...route,
+      agentId: "worker",
+      sessionKey: "agent:worker:discord:channel:c1",
+      matchedBy: "binding.channel",
+    });
+  });
+
+  it("falls back to configured route when no bound session exists", () => {
+    const route: ResolvedAgentRoute = {
+      agentId: "main",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:main:discord:channel:c1",
+      mainSessionKey: "agent:main:main",
+      lastRoutePolicy: "session",
+      matchedBy: "default",
+    };
+    const configuredRoute = {
+      route: {
+        ...route,
+        agentId: "worker",
+        sessionKey: "agent:worker:discord:channel:c1",
+        mainSessionKey: "agent:worker:main",
+        lastRoutePolicy: "session" as const,
+        matchedBy: "binding.peer" as const,
+      },
+    };
+
+    expect(
+      resolveDiscordEffectiveRoute({
+        route,
+        configuredRoute,
+      }),
+    ).toEqual(configuredRoute.route);
+  });
+
+  it("resolves the same route shape as the inline Discord route inputs", () => {
+    const cfg = buildWorkerBindingConfig({ kind: "channel", id: "c1" });
+
+    expect(
+      resolveDiscordConversationRoute({
+        cfg,
+        accountId: "default",
+        guildId: "g1",
+        memberRoleIds: [],
+        peer: { kind: "channel", id: "c1" },
+      }),
+    ).toEqual({
+      agentId: "worker",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:worker:discord:channel:c1",
+      mainSessionKey: "agent:worker:main",
+      lastRoutePolicy: "session",
+      matchedBy: "binding.peer",
+    });
+  });
+
+  it("composes route building with effective-route overrides", () => {
+    const cfg = buildWorkerBindingConfig({ kind: "direct", id: "user-1" });
+
+    expect(
+      resolveDiscordBoundConversationRoute({
+        cfg,
+        accountId: "default",
+        isDirectMessage: true,
+        isGroupDm: false,
+        directUserId: "user-1",
+        conversationId: "dm-1",
+        boundSessionKey: "agent:worker:discord:direct:user-1",
+        matchedBy: "binding.channel",
+      }),
+    ).toEqual({
+      agentId: "worker",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:worker:discord:direct:user-1",
+      mainSessionKey: "agent:worker:main",
+      lastRoutePolicy: "session",
+      matchedBy: "binding.channel",
+    });
+  });
+
+  it("ignores stale route-shaped bindings after the configured agent changes", () => {
+    const route: ResolvedAgentRoute = {
+      agentId: "newagent",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:newagent:discord:channel:c1",
+      mainSessionKey: "agent:newagent:main",
+      lastRoutePolicy: "session",
+      matchedBy: "binding.peer",
+    };
+
+    expect(
+      shouldIgnoreStaleDiscordRouteBinding({
+        route,
+        bindingRecord: {
+          bindingId: "binding-1",
+          targetSessionKey: "agent:oldagent:discord:channel:c1",
+          targetKind: "session",
+          conversation: {
+            channel: "discord",
+            accountId: "default",
+            conversationId: "c1",
+          },
+          status: "active",
+          boundAt: 1,
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("keeps explicit focus bindings even when their agent differs from routing", () => {
+    const route: ResolvedAgentRoute = {
+      agentId: "newagent",
+      channel: "discord",
+      accountId: "default",
+      sessionKey: "agent:newagent:discord:channel:c1",
+      mainSessionKey: "agent:newagent:main",
+      lastRoutePolicy: "session",
+      matchedBy: "binding.peer",
+    };
+
+    expect(
+      shouldIgnoreStaleDiscordRouteBinding({
+        route,
+        bindingRecord: {
+          bindingId: "focus-binding",
+          targetSessionKey: "agent:oldagent:discord:channel:c1",
+          targetKind: "session",
+          conversation: {
+            channel: "discord",
+            accountId: "default",
+            conversationId: "c1",
+          },
+          status: "active",
+          boundAt: 1,
+          metadata: {
+            boundBy: "user-1",
+            label: "oldagent",
+          },
+        },
+      }),
+    ).toBe(false);
+  });
+});