@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/monitor/thread-bindings.manager.ts

@@ -0,0 +1,551 @@
+import {
+  registerSessionBindingAdapter,
+  unregisterSessionBindingAdapter,
+} from "klaw/plugin-sdk/conversation-runtime";
+import { normalizeAccountId, resolveAgentIdFromSessionKey } from "klaw/plugin-sdk/routing";
+import { getRuntimeConfigSnapshot, type KlawConfig } from "klaw/plugin-sdk/runtime-config-snapshot";
+import { logVerbose } from "klaw/plugin-sdk/runtime-env";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import { createDiscordRestClient } from "../client.js";
+import { getChannel } from "../internal/discord.js";
+import {
+  createThreadForBinding,
+  createWebhookForChannel,
+  findReusableWebhook,
+  isDiscordThreadGoneError,
+  isThreadArchived,
+  maybeSendBindingMessage,
+  resolveChannelIdForBinding,
+  summarizeDiscordError,
+} from "./thread-bindings.discord-api.js";
+import {
+  resolveThreadBindingFarewellText,
+  resolveThreadBindingThreadName,
+} from "./thread-bindings.messages.js";
+import { createThreadBindingSessionAdapter } from "./thread-bindings.session-adapter.js";
+import {
+  BINDINGS_BY_THREAD_ID,
+  forgetThreadBindingToken,
+  getThreadBindingToken,
+  MANAGERS_BY_ACCOUNT_ID,
+  PERSIST_BY_ACCOUNT_ID,
+  ensureBindingsLoaded,
+  rememberThreadBindingToken,
+  normalizeTargetKind,
+  normalizeThreadBindingDurationMs,
+  normalizeThreadId,
+  rememberRecentUnboundWebhookEcho,
+  removeBindingRecord,
+  resolveBindingIdsForSession,
+  resolveBindingRecordKey,
+  resolveThreadBindingIdleTimeoutMs,
+  resolveThreadBindingInactivityExpiresAt,
+  resolveThreadBindingMaxAgeExpiresAt,
+  resolveThreadBindingMaxAgeMs,
+  resolveThreadBindingsPath,
+  saveBindingsToDisk,
+  setBindingRecord,
+  THREAD_BINDING_TOUCH_PERSIST_MIN_INTERVAL_MS,
+  shouldDefaultPersist,
+  resetThreadBindingsForTests,
+} from "./thread-bindings.state.js";
+import {
+  DEFAULT_THREAD_BINDING_IDLE_TIMEOUT_MS,
+  DEFAULT_THREAD_BINDING_MAX_AGE_MS,
+  THREAD_BINDINGS_SWEEP_INTERVAL_MS,
+  type ThreadBindingManager,
+  type ThreadBindingRecord,
+} from "./thread-bindings.types.js";
+
+function registerManager(manager: ThreadBindingManager) {
+  MANAGERS_BY_ACCOUNT_ID.set(manager.accountId, manager);
+}
+
+function unregisterManager(accountId: string, manager: ThreadBindingManager) {
+  const existing = MANAGERS_BY_ACCOUNT_ID.get(accountId);
+  if (existing === manager) {
+    MANAGERS_BY_ACCOUNT_ID.delete(accountId);
+  }
+}
+
+const SWEEPERS_BY_ACCOUNT_ID = new Map<string, () => Promise<void>>();
+
+function createNoopManager(accountIdRaw?: string): ThreadBindingManager {
+  const accountId = normalizeAccountId(accountIdRaw);
+  return {
+    accountId,
+    getIdleTimeoutMs: () => DEFAULT_THREAD_BINDING_IDLE_TIMEOUT_MS,
+    getMaxAgeMs: () => DEFAULT_THREAD_BINDING_MAX_AGE_MS,
+    getByThreadId: () => undefined,
+    getBySessionKey: () => undefined,
+    listBySessionKey: () => [],
+    listBindings: () => [],
+    touchThread: () => null,
+    bindTarget: async () => null,
+    unbindThread: () => null,
+    unbindBySessionKey: () => [],
+    stop: () => {},
+  };
+}
+
+function isDirectConversationBindingId(value?: string | null): boolean {
+  const trimmed = normalizeOptionalString(value);
+  return Boolean(trimmed && /^(user:|channel:)/i.test(trimmed));
+}
+
+export function createThreadBindingManager(params: {
+  accountId?: string;
+  token?: string;
+  cfg: KlawConfig;
+  persist?: boolean;
+  enableSweeper?: boolean;
+  idleTimeoutMs?: number;
+  maxAgeMs?: number;
+}): ThreadBindingManager {
+  ensureBindingsLoaded();
+  const accountId = normalizeAccountId(params.accountId);
+  const existing = MANAGERS_BY_ACCOUNT_ID.get(accountId);
+  if (existing) {
+    rememberThreadBindingToken({ accountId, token: params.token });
+    return existing;
+  }
+
+  rememberThreadBindingToken({ accountId, token: params.token });
+
+  const persist = params.persist ?? shouldDefaultPersist();
+  PERSIST_BY_ACCOUNT_ID.set(accountId, persist);
+  const idleTimeoutMs = normalizeThreadBindingDurationMs(
+    params.idleTimeoutMs,
+    DEFAULT_THREAD_BINDING_IDLE_TIMEOUT_MS,
+  );
+  const maxAgeMs = normalizeThreadBindingDurationMs(
+    params.maxAgeMs,
+    DEFAULT_THREAD_BINDING_MAX_AGE_MS,
+  );
+  const resolveCurrentCfg = () => getRuntimeConfigSnapshot() ?? params.cfg;
+  const resolveCurrentToken = () => getThreadBindingToken(accountId) ?? params.token;
+
+  let sweepTimer: NodeJS.Timeout | null = null;
+  const runSweepOnce = async () => {
+    const bindings = manager.listBindings();
+    if (bindings.length === 0) {
+      return;
+    }
+    let rest: ReturnType<typeof createDiscordRestClient>["rest"] | null = null;
+    for (const snapshotBinding of bindings) {
+      // Re-read live state after any awaited work from earlier iterations.
+      // This avoids unbinding based on stale snapshot data when activity touches
+      // happen while the sweeper loop is in-flight.
+      const binding = manager.getByThreadId(snapshotBinding.threadId);
+      if (!binding) {
+        continue;
+      }
+      const now = Date.now();
+      const inactivityExpiresAt = resolveThreadBindingInactivityExpiresAt({
+        record: binding,
+        defaultIdleTimeoutMs: idleTimeoutMs,
+      });
+      const maxAgeExpiresAt = resolveThreadBindingMaxAgeExpiresAt({
+        record: binding,
+        defaultMaxAgeMs: maxAgeMs,
+      });
+      const expirationCandidates: Array<{
+        reason: "idle-expired" | "max-age-expired";
+        at: number;
+      }> = [];
+      if (inactivityExpiresAt != null && now >= inactivityExpiresAt) {
+        expirationCandidates.push({ reason: "idle-expired", at: inactivityExpiresAt });
+      }
+      if (maxAgeExpiresAt != null && now >= maxAgeExpiresAt) {
+        expirationCandidates.push({ reason: "max-age-expired", at: maxAgeExpiresAt });
+      }
+      if (expirationCandidates.length > 0) {
+        expirationCandidates.sort((a, b) => a.at - b.at);
+        const reason = expirationCandidates[0]?.reason ?? "idle-expired";
+        manager.unbindThread({
+          threadId: binding.threadId,
+          reason,
+          sendFarewell: true,
+          farewellText: resolveThreadBindingFarewellText({
+            reason,
+            idleTimeoutMs: resolveThreadBindingIdleTimeoutMs({
+              record: binding,
+              defaultIdleTimeoutMs: idleTimeoutMs,
+            }),
+            maxAgeMs: resolveThreadBindingMaxAgeMs({
+              record: binding,
+              defaultMaxAgeMs: maxAgeMs,
+            }),
+          }),
+        });
+        continue;
+      }
+      if (isDirectConversationBindingId(binding.threadId)) {
+        continue;
+      }
+      if (!rest) {
+        try {
+          const cfg = resolveCurrentCfg();
+          rest = createDiscordRestClient({
+            cfg,
+            accountId,
+            token: resolveCurrentToken(),
+          }).rest;
+        } catch {
+          return;
+        }
+      }
+      try {
+        const channel = await getChannel(rest, binding.threadId);
+        if (!channel || typeof channel !== "object") {
+          logVerbose(
+            `discord thread binding sweep probe returned invalid payload for ${binding.threadId}`,
+          );
+          continue;
+        }
+        if (isThreadArchived(channel)) {
+          manager.unbindThread({
+            threadId: binding.threadId,
+            reason: "thread-archived",
+            sendFarewell: true,
+          });
+        }
+      } catch (err) {
+        if (isDiscordThreadGoneError(err)) {
+          logVerbose(
+            `discord thread binding sweep removing stale binding ${binding.threadId}: ${summarizeDiscordError(err)}`,
+          );
+          manager.unbindThread({
+            threadId: binding.threadId,
+            reason: "thread-delete",
+            sendFarewell: false,
+          });
+          continue;
+        }
+        logVerbose(
+          `discord thread binding sweep probe failed for ${binding.threadId}: ${summarizeDiscordError(err)}`,
+        );
+      }
+    }
+  };
+  SWEEPERS_BY_ACCOUNT_ID.set(accountId, runSweepOnce);
+
+  const manager: ThreadBindingManager = {
+    accountId,
+    getIdleTimeoutMs: () => idleTimeoutMs,
+    getMaxAgeMs: () => maxAgeMs,
+    getByThreadId: (threadId) => {
+      const key = resolveBindingRecordKey({
+        accountId,
+        threadId,
+      });
+      if (!key) {
+        return undefined;
+      }
+      const entry = BINDINGS_BY_THREAD_ID.get(key);
+      if (!entry || entry.accountId !== accountId) {
+        return undefined;
+      }
+      return entry;
+    },
+    getBySessionKey: (targetSessionKey) => {
+      const all = manager.listBySessionKey(targetSessionKey);
+      return all[0];
+    },
+    listBySessionKey: (targetSessionKey) => {
+      const ids = resolveBindingIdsForSession({
+        targetSessionKey,
+        accountId,
+      });
+      return ids
+        .map((bindingKey) => BINDINGS_BY_THREAD_ID.get(bindingKey))
+        .filter((entry): entry is ThreadBindingRecord => Boolean(entry));
+    },
+    listBindings: () =>
+      [...BINDINGS_BY_THREAD_ID.values()].filter((entry) => entry.accountId === accountId),
+    touchThread: (touchParams) => {
+      const key = resolveBindingRecordKey({
+        accountId,
+        threadId: touchParams.threadId,
+      });
+      if (!key) {
+        return null;
+      }
+      const existing = BINDINGS_BY_THREAD_ID.get(key);
+      if (!existing || existing.accountId !== accountId) {
+        return null;
+      }
+      const now = Date.now();
+      const at =
+        typeof touchParams.at === "number" && Number.isFinite(touchParams.at)
+          ? Math.max(0, Math.floor(touchParams.at))
+          : now;
+      const nextRecord: ThreadBindingRecord = {
+        ...existing,
+        lastActivityAt: Math.max(existing.lastActivityAt || 0, at),
+      };
+      setBindingRecord(nextRecord);
+      if (touchParams.persist ?? persist) {
+        saveBindingsToDisk({
+          minIntervalMs: THREAD_BINDING_TOUCH_PERSIST_MIN_INTERVAL_MS,
+        });
+      }
+      return nextRecord;
+    },
+    bindTarget: async (bindParams) => {
+      const cfg = resolveCurrentCfg();
+      let threadId = normalizeThreadId(bindParams.threadId);
+      let channelId = normalizeOptionalString(bindParams.channelId) ?? "";
+      const directConversationBinding =
+        isDirectConversationBindingId(threadId) || isDirectConversationBindingId(channelId);
+
+      if (!threadId && bindParams.createThread) {
+        if (!channelId) {
+          return null;
+        }
+        const threadName = resolveThreadBindingThreadName({
+          agentId: bindParams.agentId,
+          label: bindParams.label,
+        });
+        threadId =
+          (await createThreadForBinding({
+            cfg,
+            accountId,
+            token: resolveCurrentToken(),
+            channelId,
+            threadName: normalizeOptionalString(bindParams.threadName) ?? threadName,
+          })) ?? undefined;
+      }
+
+      if (!threadId) {
+        return null;
+      }
+
+      if (!channelId && directConversationBinding) {
+        channelId = threadId;
+      }
+
+      if (!channelId) {
+        channelId =
+          (await resolveChannelIdForBinding({
+            cfg,
+            accountId,
+            token: resolveCurrentToken(),
+            threadId,
+            channelId: bindParams.channelId,
+          })) ?? "";
+      }
+      if (!channelId) {
+        return null;
+      }
+
+      const existing = manager.getByThreadId(threadId);
+      const targetSessionKey = normalizeOptionalString(bindParams.targetSessionKey) ?? "";
+      if (!targetSessionKey) {
+        return null;
+      }
+
+      const targetKind = normalizeTargetKind(bindParams.targetKind, targetSessionKey);
+      let webhookId =
+        normalizeOptionalString(bindParams.webhookId) ??
+        normalizeOptionalString(existing?.webhookId) ??
+        "";
+      let webhookToken =
+        normalizeOptionalString(bindParams.webhookToken) ??
+        normalizeOptionalString(existing?.webhookToken) ??
+        "";
+      if (!directConversationBinding && (!webhookId || !webhookToken)) {
+        const cachedWebhook = findReusableWebhook({ accountId, channelId });
+        webhookId = cachedWebhook.webhookId ?? "";
+        webhookToken = cachedWebhook.webhookToken ?? "";
+      }
+      if (!directConversationBinding && (!webhookId || !webhookToken)) {
+        const createdWebhook = await createWebhookForChannel({
+          cfg,
+          accountId,
+          token: resolveCurrentToken(),
+          channelId,
+        });
+        webhookId = createdWebhook.webhookId ?? "";
+        webhookToken = createdWebhook.webhookToken ?? "";
+      }
+
+      const now = Date.now();
+      const record: ThreadBindingRecord = {
+        accountId,
+        channelId,
+        threadId,
+        targetKind,
+        targetSessionKey,
+        agentId:
+          normalizeOptionalString(bindParams.agentId) ??
+          normalizeOptionalString(existing?.agentId) ??
+          resolveAgentIdFromSessionKey(targetSessionKey),
+        label:
+          normalizeOptionalString(bindParams.label) ?? normalizeOptionalString(existing?.label),
+        webhookId: webhookId || undefined,
+        webhookToken: webhookToken || undefined,
+        boundBy:
+          normalizeOptionalString(bindParams.boundBy) ??
+          normalizeOptionalString(existing?.boundBy) ??
+          "system",
+        boundAt: now,
+        lastActivityAt: now,
+        idleTimeoutMs:
+          typeof existing?.idleTimeoutMs === "number" ? existing.idleTimeoutMs : idleTimeoutMs,
+        maxAgeMs: typeof existing?.maxAgeMs === "number" ? existing.maxAgeMs : maxAgeMs,
+        metadata:
+          bindParams.metadata && typeof bindParams.metadata === "object"
+            ? { ...existing?.metadata, ...bindParams.metadata }
+            : existing?.metadata
+              ? { ...existing.metadata }
+              : undefined,
+      };
+
+      setBindingRecord(record);
+      if (persist) {
+        saveBindingsToDisk();
+      }
+
+      const introText = bindParams.introText?.trim();
+      if (introText && cfg) {
+        void maybeSendBindingMessage({ cfg, record, text: introText });
+      }
+      return record;
+    },
+    unbindThread: (unbindParams) => {
+      const bindingKey = resolveBindingRecordKey({
+        accountId,
+        threadId: unbindParams.threadId,
+      });
+      if (!bindingKey) {
+        return null;
+      }
+      const existing = BINDINGS_BY_THREAD_ID.get(bindingKey);
+      if (!existing || existing.accountId !== accountId) {
+        return null;
+      }
+      const removed = removeBindingRecord(bindingKey);
+      if (!removed) {
+        return null;
+      }
+      rememberRecentUnboundWebhookEcho(removed);
+      if (persist) {
+        saveBindingsToDisk();
+      }
+      if (unbindParams.sendFarewell !== false) {
+        const cfg = resolveCurrentCfg();
+        const farewell = resolveThreadBindingFarewellText({
+          reason: unbindParams.reason,
+          farewellText: unbindParams.farewellText,
+          idleTimeoutMs: resolveThreadBindingIdleTimeoutMs({
+            record: removed,
+            defaultIdleTimeoutMs: idleTimeoutMs,
+          }),
+          maxAgeMs: resolveThreadBindingMaxAgeMs({
+            record: removed,
+            defaultMaxAgeMs: maxAgeMs,
+          }),
+        });
+        // Use bot send path for farewell messages so unbound threads don't process
+        // webhook echoes as fresh inbound events when allowBots is enabled.
+        if (cfg) {
+          void maybeSendBindingMessage({
+            cfg,
+            record: removed,
+            text: farewell,
+            preferWebhook: false,
+          });
+        }
+      }
+      return removed;
+    },
+    unbindBySessionKey: (unbindParams) => {
+      const ids = resolveBindingIdsForSession({
+        targetSessionKey: unbindParams.targetSessionKey,
+        accountId,
+        targetKind: unbindParams.targetKind,
+      });
+      if (ids.length === 0) {
+        return [];
+      }
+      const removed: ThreadBindingRecord[] = [];
+      for (const bindingKey of ids) {
+        const binding = BINDINGS_BY_THREAD_ID.get(bindingKey);
+        if (!binding) {
+          continue;
+        }
+        const entry = manager.unbindThread({
+          threadId: binding.threadId,
+          reason: unbindParams.reason,
+          sendFarewell: unbindParams.sendFarewell,
+          farewellText: unbindParams.farewellText,
+        });
+        if (entry) {
+          removed.push(entry);
+        }
+      }
+      return removed;
+    },
+    stop: () => {
+      if (sweepTimer) {
+        clearInterval(sweepTimer);
+        sweepTimer = null;
+      }
+      SWEEPERS_BY_ACCOUNT_ID.delete(accountId);
+      unregisterManager(accountId, manager);
+      unregisterSessionBindingAdapter({
+        channel: "discord",
+        accountId,
+        adapter: sessionBindingAdapter,
+      });
+      forgetThreadBindingToken(accountId);
+    },
+  };
+
+  if (params.enableSweeper !== false) {
+    sweepTimer = setInterval(() => {
+      void runSweepOnce();
+    }, THREAD_BINDINGS_SWEEP_INTERVAL_MS);
+    // Keep the production process free to exit, but avoid breaking fake-timer
+    // sweeper tests where unref'd intervals may never fire.
+    if (!(process.env.VITEST || process.env.NODE_ENV === "test")) {
+      sweepTimer.unref?.();
+    }
+  }
+
+  const sessionBindingAdapter = createThreadBindingSessionAdapter({
+    accountId,
+    manager,
+    defaults: { idleTimeoutMs, maxAgeMs },
+    resolveCurrentCfg,
+    resolveCurrentToken,
+  });
+
+  registerSessionBindingAdapter(sessionBindingAdapter);
+
+  registerManager(manager);
+  return manager;
+}
+
+export function createNoopThreadBindingManager(accountId?: string): ThreadBindingManager {
+  return createNoopManager(accountId);
+}
+
+export function getThreadBindingManager(accountId?: string): ThreadBindingManager | null {
+  const normalized = normalizeAccountId(accountId);
+  return MANAGERS_BY_ACCOUNT_ID.get(normalized) ?? null;
+}
+
+export const testing = {
+  resolveThreadBindingsPath,
+  resolveThreadBindingThreadName,
+  resetThreadBindingsForTests,
+  runThreadBindingSweepForAccount: async (accountId?: string) => {
+    const sweep = SWEEPERS_BY_ACCOUNT_ID.get(normalizeAccountId(accountId));
+    if (sweep) {
+      await sweep();
+    }
+  },
+};
+export { testing as __testing };

package/src/monitor/thread-bindings.messages.ts

@@ -0,0 +1,6 @@
+export {
+  resolveThreadBindingFarewellText,
+  resolveThreadBindingIntroText,
+  resolveThreadBindingThreadName,
+  formatThreadBindingDurationLabel,
+} from "klaw/plugin-sdk/conversation-runtime";

package/src/monitor/thread-bindings.persona.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import {
+  resolveThreadBindingPersona,
+  resolveThreadBindingPersonaFromRecord,
+} from "./thread-bindings.persona.js";
+import type { ThreadBindingRecord } from "./thread-bindings.types.js";
+
+describe("thread binding persona", () => {
+  it("prefers explicit label and prefixes with gear", () => {
+    expect(resolveThreadBindingPersona({ label: "codex thread", agentId: "codex" })).toBe(
+      "⚙️ codex thread",
+    );
+  });
+
+  it("falls back to agent id when label is missing", () => {
+    expect(resolveThreadBindingPersona({ agentId: "codex" })).toBe("⚙️ codex");
+  });
+
+  it("builds persona from binding record", () => {
+    const record = {
+      accountId: "default",
+      channelId: "parent-1",
+      threadId: "thread-1",
+      targetKind: "acp",
+      targetSessionKey: "agent:codex:acp:session-1",
+      agentId: "codex",
+      boundBy: "system",
+      boundAt: Date.now(),
+      lastActivityAt: Date.now(),
+      label: "codex-thread",
+    } satisfies ThreadBindingRecord;
+    expect(resolveThreadBindingPersonaFromRecord(record)).toBe("⚙️ codex-thread");
+  });
+});

package/src/monitor/thread-bindings.persona.ts

@@ -0,0 +1,25 @@
+import { SYSTEM_MARK } from "klaw/plugin-sdk/text-chunking";
+import type { ThreadBindingRecord } from "./thread-bindings.types.js";
+
+const THREAD_BINDING_PERSONA_MAX_CHARS = 80;
+
+function normalizePersonaLabel(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const normalized = value.replace(/\s+/g, " ").trim();
+  return normalized || undefined;
+}
+
+export function resolveThreadBindingPersona(params: { label?: string; agentId?: string }): string {
+  const base =
+    normalizePersonaLabel(params.label) || normalizePersonaLabel(params.agentId) || "agent";
+  return `${SYSTEM_MARK} ${base}`.slice(0, THREAD_BINDING_PERSONA_MAX_CHARS);
+}
+
+export function resolveThreadBindingPersonaFromRecord(record: ThreadBindingRecord): string {
+  return resolveThreadBindingPersona({
+    label: record.label,
+    agentId: record.agentId,
+  });
+}