@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/subagent-hooks.ts

@@ -0,0 +1,232 @@
+import type { KlawPluginApi } from "klaw/plugin-sdk/channel-plugin-common";
+import {
+  formatThreadBindingDisabledError,
+  formatThreadBindingSpawnDisabledError,
+  resolveThreadBindingSpawnPolicy,
+} from "klaw/plugin-sdk/conversation-runtime";
+import {
+  normalizeOptionalLowercaseString,
+  normalizeOptionalStringifiedId,
+} from "klaw/plugin-sdk/string-coerce-runtime";
+import { resolveDiscordAccount } from "./accounts.js";
+import {
+  autoBindSpawnedDiscordSubagent,
+  listThreadBindingsBySessionKey,
+  type ThreadBindingTargetKind,
+  unbindThreadBindingsBySessionKey,
+} from "./monitor/thread-bindings.js";
+
+function summarizeError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  if (typeof err === "string") {
+    return err;
+  }
+  return "error";
+}
+
+type DiscordSubagentSpawningEvent = {
+  threadRequested?: boolean;
+  requester?: {
+    channel?: string;
+    accountId?: string;
+    to?: string;
+    threadId?: string | number;
+  };
+  childSessionKey: string;
+  agentId: string;
+  label?: string;
+};
+
+type DiscordSubagentEndedEvent = {
+  targetSessionKey: string;
+  accountId?: string;
+  targetKind?: ThreadBindingTargetKind;
+  reason?: string;
+  sendFarewell?: boolean;
+};
+
+type DiscordSubagentDeliveryTargetEvent = {
+  expectsCompletionMessage?: boolean;
+  childSessionKey: string;
+  requesterOrigin?: {
+    channel?: string;
+    accountId?: string;
+    threadId?: string | number;
+  };
+};
+
+type DiscordSubagentSpawningResult =
+  | {
+      status: "ok";
+      threadBindingReady?: boolean;
+      deliveryOrigin?: {
+        channel: "discord";
+        accountId?: string;
+        to: string;
+        threadId?: string | number;
+      };
+    }
+  | { status: "error"; error: string }
+  | undefined;
+
+type DiscordSubagentDeliveryTargetResult =
+  | {
+      origin: {
+        channel: "discord";
+        accountId?: string;
+        to: string;
+        threadId?: string | number;
+      };
+    }
+  | undefined;
+
+function normalizeThreadBindingTargetKind(raw?: string): ThreadBindingTargetKind | undefined {
+  const normalized = normalizeOptionalLowercaseString(raw);
+  if (normalized === "subagent" || normalized === "acp") {
+    return normalized;
+  }
+  return undefined;
+}
+
+export async function handleDiscordSubagentSpawning(
+  api: KlawPluginApi,
+  event: DiscordSubagentSpawningEvent,
+): Promise<DiscordSubagentSpawningResult> {
+  if (!event.threadRequested) {
+    return undefined;
+  }
+  const channel = normalizeOptionalLowercaseString(event.requester?.channel);
+  if (channel !== "discord") {
+    return undefined;
+  }
+  const account = resolveDiscordAccount({
+    cfg: api.config,
+    accountId: event.requester?.accountId,
+  });
+  const threadBindingPolicy = resolveThreadBindingSpawnPolicy({
+    cfg: api.config,
+    channel: "discord",
+    accountId: account.accountId,
+    kind: "subagent",
+  });
+  if (!threadBindingPolicy.enabled) {
+    return {
+      status: "error" as const,
+      error: formatThreadBindingDisabledError({
+        channel: threadBindingPolicy.channel,
+        accountId: threadBindingPolicy.accountId,
+        kind: "subagent",
+      }),
+    };
+  }
+  if (!threadBindingPolicy.spawnEnabled) {
+    return {
+      status: "error" as const,
+      error: formatThreadBindingSpawnDisabledError({
+        channel: threadBindingPolicy.channel,
+        accountId: threadBindingPolicy.accountId,
+        kind: "subagent",
+      }),
+    };
+  }
+  try {
+    const agentId = event.agentId?.trim() || "subagent";
+    const binding = await autoBindSpawnedDiscordSubagent({
+      cfg: api.config,
+      accountId: account.accountId,
+      channel: event.requester?.channel,
+      to: event.requester?.to,
+      threadId: event.requester?.threadId,
+      childSessionKey: event.childSessionKey,
+      agentId,
+      label: event.label,
+      boundBy: "system",
+    });
+    if (!binding) {
+      return {
+        status: "error" as const,
+        error:
+          "Unable to create or bind a Discord thread for this subagent session. Session mode is unavailable for this target.",
+      };
+    }
+    return {
+      status: "ok" as const,
+      threadBindingReady: true,
+      deliveryOrigin: {
+        channel: "discord",
+        accountId: account.accountId,
+        to: `channel:${binding.threadId}`,
+        threadId: binding.threadId,
+      },
+    };
+  } catch (err) {
+    return {
+      status: "error" as const,
+      error: `Discord thread bind failed: ${summarizeError(err)}`,
+    };
+  }
+}
+
+export function handleDiscordSubagentEnded(event: DiscordSubagentEndedEvent) {
+  unbindThreadBindingsBySessionKey({
+    targetSessionKey: event.targetSessionKey,
+    accountId: event.accountId,
+    targetKind: normalizeThreadBindingTargetKind(event.targetKind),
+    reason: event.reason,
+    sendFarewell: event.sendFarewell,
+  });
+}
+
+export function handleDiscordSubagentDeliveryTarget(
+  event: DiscordSubagentDeliveryTargetEvent,
+): DiscordSubagentDeliveryTargetResult {
+  if (!event.expectsCompletionMessage) {
+    return undefined;
+  }
+  const requesterChannel = normalizeOptionalLowercaseString(event.requesterOrigin?.channel);
+  if (requesterChannel !== "discord") {
+    return undefined;
+  }
+  const requesterAccountId = event.requesterOrigin?.accountId?.trim();
+  const requesterThreadId =
+    event.requesterOrigin?.threadId != null && event.requesterOrigin.threadId !== ""
+      ? (normalizeOptionalStringifiedId(event.requesterOrigin.threadId) ?? "")
+      : "";
+  const bindings = listThreadBindingsBySessionKey({
+    targetSessionKey: event.childSessionKey,
+    ...(requesterAccountId ? { accountId: requesterAccountId } : {}),
+    targetKind: "subagent",
+  });
+  if (bindings.length === 0) {
+    return undefined;
+  }
+
+  let binding: (typeof bindings)[number] | undefined;
+  if (requesterThreadId) {
+    binding = bindings.find((entry) => {
+      if (entry.threadId !== requesterThreadId) {
+        return false;
+      }
+      if (requesterAccountId && entry.accountId !== requesterAccountId) {
+        return false;
+      }
+      return true;
+    });
+  }
+  if (!binding && bindings.length === 1) {
+    binding = bindings[0];
+  }
+  if (!binding) {
+    return undefined;
+  }
+  return {
+    origin: {
+      channel: "discord" as const,
+      accountId: binding.accountId,
+      to: `channel:${binding.threadId}`,
+      threadId: binding.threadId,
+    },
+  };
+}

package/src/target-parsing.ts

@@ -0,0 +1,70 @@
+import {
+  buildMessagingTarget,
+  parseMentionPrefixOrAtUserTarget,
+  requireTargetKind,
+  type MessagingTarget,
+  type MessagingTargetKind,
+  type MessagingTargetParseOptions,
+} from "klaw/plugin-sdk/messaging-targets";
+
+export type DiscordTargetKind = MessagingTargetKind;
+
+export type DiscordTarget = MessagingTarget;
+
+export type DiscordTargetParseOptions = MessagingTargetParseOptions;
+
+export function parseDiscordTarget(
+  raw: string,
+  options: DiscordTargetParseOptions = {},
+): DiscordTarget | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const providerPrefixedTarget = parseDiscordProviderPrefixedTarget(trimmed);
+  if (providerPrefixedTarget) {
+    return providerPrefixedTarget;
+  }
+  const userTarget = parseMentionPrefixOrAtUserTarget({
+    raw: trimmed,
+    mentionPattern: /^<@!?(\d+)>$/,
+    prefixes: [
+      { prefix: "user:", kind: "user" },
+      { prefix: "channel:", kind: "channel" },
+      { prefix: "discord:", kind: "user" },
+    ],
+    atUserPattern: /^\d+$/,
+    atUserErrorMessage: "Discord DMs require a user id (use user:<id> or a <@id> mention)",
+  });
+  if (userTarget) {
+    return userTarget;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    if (options.defaultKind) {
+      return buildMessagingTarget(options.defaultKind, trimmed, trimmed);
+    }
+    throw new Error(
+      options.ambiguousMessage ??
+        `Ambiguous Discord recipient "${trimmed}". For DMs use "user:${trimmed}" or "<@${trimmed}>"; for channels use "channel:${trimmed}".`,
+    );
+  }
+  return buildMessagingTarget("channel", trimmed, trimmed);
+}
+
+function parseDiscordProviderPrefixedTarget(raw: string): DiscordTarget | undefined {
+  const match = /^discord:(channel|user):(.+)$/i.exec(raw);
+  if (!match) {
+    return undefined;
+  }
+  const kind = match[1]?.toLowerCase() as "channel" | "user" | undefined;
+  const id = match[2]?.trim();
+  if (!kind || !id) {
+    return undefined;
+  }
+  return buildMessagingTarget(kind, id, `${kind}:${id}`);
+}
+
+export function resolveDiscordChannelId(raw: string): string {
+  const target = parseDiscordTarget(raw, { defaultKind: "channel" });
+  return requireTargetKind({ platform: "Discord", target, kind: "channel" });
+}

package/src/target-resolver.ts

@@ -0,0 +1,129 @@
+import type { DirectoryConfigParams } from "klaw/plugin-sdk/directory-runtime";
+import { buildMessagingTarget, type MessagingTarget } from "klaw/plugin-sdk/messaging-targets";
+import { resolveDiscordAccount, resolveDiscordAccountAllowFrom } from "./accounts.js";
+import { rememberDiscordDirectoryUser } from "./directory-cache.js";
+import { listDiscordDirectoryPeersLive } from "./directory-live.js";
+import { allowFromContainsDiscordUserId } from "./normalize.js";
+import { parseDiscordSendTarget } from "./send-target-parsing.js";
+import { type DiscordTargetParseOptions } from "./target-parsing.js";
+
+/**
+ * Resolve a Discord username to user ID using the directory lookup.
+ * This enables sending DMs by username instead of requiring explicit user IDs.
+ */
+export async function resolveDiscordTarget(
+  raw: string,
+  options: DirectoryConfigParams,
+  parseOptions: DiscordTargetParseOptions = {},
+): Promise<MessagingTarget | undefined> {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const likelyUsername = isLikelyUsername(trimmed);
+  const shouldLookup = isExplicitUserLookup(trimmed, parseOptions) || likelyUsername;
+
+  if (
+    /^\d+$/.test(trimmed) &&
+    parseOptions.defaultKind !== "user" &&
+    isConfiguredAllowedDiscordDmUser(trimmed, options)
+  ) {
+    return buildMessagingTarget("user", trimmed, trimmed);
+  }
+
+  // Parse directly if it's already a known format. Use a safe parse so ambiguous
+  // numeric targets don't throw when we still want to attempt username lookup.
+  const directParse = safeParseDiscordTarget(trimmed, parseOptions);
+  if (directParse && directParse.kind !== "channel" && !likelyUsername) {
+    return directParse;
+  }
+
+  if (!shouldLookup) {
+    return directParse ?? parseDiscordSendTarget(trimmed, parseOptions);
+  }
+
+  try {
+    const directoryEntries = await listDiscordDirectoryPeersLive({
+      ...options,
+      query: trimmed,
+      limit: 1,
+    });
+
+    const match = directoryEntries[0];
+    if (match && match.kind === "user") {
+      const userId = match.id.replace(/^user:/, "");
+      const resolvedAccountId = resolveDiscordAccount({
+        cfg: options.cfg,
+        accountId: options.accountId,
+      }).accountId;
+      rememberDiscordDirectoryUser({
+        accountId: resolvedAccountId,
+        userId,
+        handles: [trimmed, match.name, match.handle],
+      });
+      return buildMessagingTarget("user", userId, trimmed);
+    }
+  } catch {
+    // Preserve legacy fallback behavior for channel names and direct ids.
+  }
+
+  return parseDiscordSendTarget(trimmed, parseOptions);
+}
+
+export async function parseAndResolveDiscordTarget(
+  raw: string,
+  options: DirectoryConfigParams,
+  parseOptions: DiscordTargetParseOptions = {},
+): Promise<MessagingTarget> {
+  const resolved =
+    (await resolveDiscordTarget(raw, options, parseOptions)) ??
+    parseDiscordSendTarget(raw, parseOptions);
+  if (!resolved) {
+    throw new Error("Recipient is required for Discord sends");
+  }
+  return resolved;
+}
+
+function safeParseDiscordTarget(
+  input: string,
+  options: DiscordTargetParseOptions,
+): MessagingTarget | undefined {
+  try {
+    return parseDiscordSendTarget(input, options);
+  } catch {
+    return undefined;
+  }
+}
+
+function isConfiguredAllowedDiscordDmUser(input: string, options: DirectoryConfigParams): boolean {
+  const allowFrom =
+    resolveDiscordAccountAllowFrom({
+      cfg: options.cfg,
+      accountId: options.accountId,
+    }) ?? [];
+  return allowFromContainsDiscordUserId(allowFrom, input);
+}
+
+function isExplicitUserLookup(input: string, options: DiscordTargetParseOptions): boolean {
+  if (/^<@!?(\d+)>$/.test(input)) {
+    return true;
+  }
+  if (/^(user:|discord:)/.test(input)) {
+    return true;
+  }
+  if (input.startsWith("@")) {
+    return true;
+  }
+  if (/^\d+$/.test(input)) {
+    return options.defaultKind === "user";
+  }
+  return false;
+}
+
+function isLikelyUsername(input: string): boolean {
+  if (/^(user:|channel:|discord:|@|<@!?)|[\d]+$/.test(input)) {
+    return false;
+  }
+  return true;
+}