@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/status-issues.ts

@@ -0,0 +1,198 @@
+import type { ChannelAccountSnapshot, ChannelStatusIssue } from "klaw/plugin-sdk/channel-contract";
+import {
+  appendMatchMetadata,
+  asString,
+  isRecord,
+  resolveEnabledConfiguredAccountId,
+} from "klaw/plugin-sdk/status-helpers";
+
+type DiscordIntentSummary = {
+  messageContent?: "enabled" | "limited" | "disabled";
+};
+
+type DiscordApplicationSummary = {
+  intents?: DiscordIntentSummary;
+};
+
+type DiscordAccountStatus = {
+  accountId?: unknown;
+  enabled?: unknown;
+  configured?: unknown;
+  running?: unknown;
+  connected?: unknown;
+  healthState?: unknown;
+  application?: unknown;
+  audit?: unknown;
+};
+
+type DiscordPermissionsAuditSummary = {
+  unresolvedChannels?: number;
+  channels?: Array<{
+    channelId: string;
+    ok?: boolean;
+    missing?: string[];
+    error?: string | null;
+    matchKey?: string;
+    matchSource?: string;
+  }>;
+};
+
+function readDiscordAccountStatus(value: ChannelAccountSnapshot): DiscordAccountStatus | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  return {
+    accountId: value.accountId,
+    enabled: value.enabled,
+    configured: value.configured,
+    running: value.running,
+    connected: value.connected,
+    healthState: value.healthState,
+    application: value.application,
+    audit: value.audit,
+  };
+}
+
+function readDiscordApplicationSummary(value: unknown): DiscordApplicationSummary {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const intentsRaw = value.intents;
+  if (!isRecord(intentsRaw)) {
+    return {};
+  }
+  return {
+    intents: {
+      messageContent:
+        intentsRaw.messageContent === "enabled" ||
+        intentsRaw.messageContent === "limited" ||
+        intentsRaw.messageContent === "disabled"
+          ? intentsRaw.messageContent
+          : undefined,
+    },
+  };
+}
+
+function readDiscordPermissionsAuditSummary(value: unknown): DiscordPermissionsAuditSummary {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const unresolvedChannels =
+    typeof value.unresolvedChannels === "number" && Number.isFinite(value.unresolvedChannels)
+      ? value.unresolvedChannels
+      : undefined;
+  const channelsRaw = value.channels;
+  const channels = Array.isArray(channelsRaw)
+    ? (channelsRaw
+        .map((entry) => {
+          if (!isRecord(entry)) {
+            return null;
+          }
+          const channelId = asString(entry.channelId);
+          if (!channelId) {
+            return null;
+          }
+          const ok = typeof entry.ok === "boolean" ? entry.ok : undefined;
+          const missing = Array.isArray(entry.missing)
+            ? entry.missing.map((v) => asString(v)).filter(Boolean)
+            : undefined;
+          const error = asString(entry.error) ?? null;
+          const matchKey = asString(entry.matchKey) ?? undefined;
+          const matchSource = asString(entry.matchSource) ?? undefined;
+          return {
+            channelId,
+            ok,
+            missing: missing?.length ? missing : undefined,
+            error,
+            matchKey,
+            matchSource,
+          };
+        })
+        .filter(Boolean) as DiscordPermissionsAuditSummary["channels"])
+    : undefined;
+  return { unresolvedChannels, channels };
+}
+
+export function collectDiscordStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+): ChannelStatusIssue[] {
+  const issues: ChannelStatusIssue[] = [];
+  for (const entry of accounts) {
+    const account = readDiscordAccountStatus(entry);
+    if (!account) {
+      continue;
+    }
+    const accountId = resolveEnabledConfiguredAccountId(account);
+    if (!accountId) {
+      continue;
+    }
+
+    const running = account.running === true;
+    const healthState = asString(account.healthState);
+    if (
+      healthState === "stale-socket" ||
+      healthState === "stuck" ||
+      healthState === "disconnected" ||
+      healthState === "not-running"
+    ) {
+      const runningLabel = running ? "running" : "not running";
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "runtime",
+        message: `Discord gateway transport is degraded (${healthState}; account is ${runningLabel}).`,
+        fix: "Check gateway event-loop health and Discord connectivity, then restart the Discord channel or gateway if the transport does not recover.",
+      });
+    } else if (running && account.connected === false) {
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "runtime",
+        message: "Discord gateway transport is running but disconnected.",
+        fix: "Check gateway logs for Discord websocket errors and wait for reconnect; restart the Discord channel or gateway if it does not recover.",
+      });
+    }
+
+    const app = readDiscordApplicationSummary(account.application);
+    const messageContent = app.intents?.messageContent;
+    if (messageContent === "disabled") {
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "intent",
+        message: "Message Content Intent is disabled. Bot may not see normal channel messages.",
+        fix: "Enable Message Content Intent in Discord Dev Portal → Bot → Privileged Gateway Intents, or require mention-only operation.",
+      });
+    }
+
+    const audit = readDiscordPermissionsAuditSummary(account.audit);
+    if (audit.unresolvedChannels && audit.unresolvedChannels > 0) {
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "config",
+        message: `Some configured guild channels are not numeric IDs (unresolvedChannels=${audit.unresolvedChannels}). Permission audit can only check numeric channel IDs.`,
+        fix: "Use numeric channel IDs as keys in channels.discord.guilds.*.channels (then rerun channels status --probe).",
+      });
+    }
+    for (const channel of audit.channels ?? []) {
+      if (channel.ok === true) {
+        continue;
+      }
+      const missing = channel.missing?.length ? ` missing ${channel.missing.join(", ")}` : "";
+      const error = channel.error ? `: ${channel.error}` : "";
+      const baseMessage = `Channel ${channel.channelId} permission check failed.${missing}${error}`;
+      issues.push({
+        channel: "discord",
+        accountId,
+        kind: "permissions",
+        message: appendMatchMetadata(baseMessage, {
+          matchKey: channel.matchKey,
+          matchSource: channel.matchSource,
+        }),
+        fix: "Ensure the bot role can view + send in this channel (and that channel overrides don't deny it).",
+      });
+    }
+  }
+  return issues;
+}

package/src/subagent-hooks.test.ts

@@ -0,0 +1,465 @@
+import {
+  getRequiredHookHandler,
+  registerHookHandlersForTest,
+} from "klaw/plugin-sdk/channel-test-helpers";
+import type { KlawPluginApi } from "klaw/plugin-sdk/core";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+type ThreadBindingRecord = {
+  accountId: string;
+  threadId: string;
+};
+
+type MockResolvedDiscordAccount = {
+  accountId: string;
+  config: {
+    threadBindings?: {
+      enabled?: boolean;
+      spawnSessions?: boolean;
+    };
+  };
+};
+
+type MockResolveDiscordAccountParams = {
+  cfg?: {
+    channels?: {
+      discord?: {
+        defaultAccount?: string;
+        accounts?: Record<
+          string,
+          { threadBindings?: MockResolvedDiscordAccount["config"]["threadBindings"] }
+        >;
+      };
+    };
+  };
+  accountId?: string;
+};
+
+const hookMocks = vi.hoisted(() => {
+  const resolveDiscordAccountImpl = (
+    params?: MockResolveDiscordAccountParams,
+  ): MockResolvedDiscordAccount => {
+    const accountId =
+      params?.accountId?.trim() || params?.cfg?.channels?.discord?.defaultAccount || "default";
+    return {
+      accountId,
+      config: {
+        threadBindings: params?.cfg?.channels?.discord?.accounts?.[accountId]?.threadBindings ?? {
+          spawnSessions: true,
+        },
+      },
+    };
+  };
+  return {
+    resolveDiscordAccountImpl,
+    resolveDiscordAccount: vi.fn(resolveDiscordAccountImpl),
+    autoBindSpawnedDiscordSubagent: vi.fn(
+      async (): Promise<{ threadId: string } | null> => ({ threadId: "thread-1" }),
+    ),
+    listThreadBindingsBySessionKey: vi.fn((_params?: unknown): ThreadBindingRecord[] => []),
+    unbindThreadBindingsBySessionKey: vi.fn(() => []),
+  };
+});
+
+let registerDiscordSubagentHooks: typeof import("../subagent-hooks-api.js").registerDiscordSubagentHooks;
+
+vi.mock("./accounts.js", () => ({
+  resolveDiscordAccount: hookMocks.resolveDiscordAccount,
+}));
+vi.mock("./monitor/thread-bindings.js", () => ({
+  autoBindSpawnedDiscordSubagent: hookMocks.autoBindSpawnedDiscordSubagent,
+  listThreadBindingsBySessionKey: hookMocks.listThreadBindingsBySessionKey,
+  unbindThreadBindingsBySessionKey: hookMocks.unbindThreadBindingsBySessionKey,
+}));
+
+function registerHandlersForTest(
+  config: Record<string, unknown> = {
+    channels: {
+      discord: {
+        threadBindings: {
+          spawnSessions: true,
+        },
+      },
+    },
+  },
+) {
+  return registerHookHandlersForTest<KlawPluginApi>({
+    config,
+    register: registerDiscordSubagentHooks,
+  });
+}
+
+async function resolveSubagentDeliveryTargetForTest(requesterOrigin: {
+  channel: string;
+  accountId: string;
+  to: string;
+  threadId?: string;
+}) {
+  const handlers = registerHandlersForTest();
+  const handler = getRequiredHookHandler(handlers, "subagent_delivery_target");
+  return await handler(
+    {
+      childSessionKey: "agent:main:subagent:child",
+      requesterSessionKey: "agent:main:main",
+      requesterOrigin,
+      childRunId: "run-1",
+      spawnMode: "session",
+      expectsCompletionMessage: true,
+    },
+    {},
+  );
+}
+
+function createSpawnEvent(overrides?: {
+  childSessionKey?: string;
+  agentId?: string;
+  label?: string;
+  mode?: string;
+  requester?: {
+    channel?: string;
+    accountId?: string | undefined;
+    to?: string;
+    threadId?: string;
+  };
+  threadRequested?: boolean;
+}): {
+  childSessionKey: string;
+  agentId: string;
+  label: string;
+  mode: string;
+  requester: {
+    channel: string;
+    accountId?: string;
+    to: string;
+    threadId?: string;
+  };
+  threadRequested: boolean;
+} {
+  const base = {
+    childSessionKey: "agent:main:subagent:child",
+    agentId: "main",
+    label: "banana",
+    mode: "session",
+    requester: {
+      channel: "discord",
+      accountId: "work",
+      to: "channel:123",
+      threadId: "456",
+    },
+    threadRequested: true,
+  };
+  return {
+    ...base,
+    ...overrides,
+    requester: {
+      ...base.requester,
+      ...overrides?.requester,
+    },
+  };
+}
+
+function createSpawnEventWithoutThread() {
+  return createSpawnEvent({
+    label: "",
+    requester: { threadId: undefined },
+  });
+}
+
+async function runSubagentSpawning(
+  config?: Record<string, unknown>,
+  event = createSpawnEventWithoutThread(),
+) {
+  const handlers = registerHandlersForTest(config);
+  const handler = getRequiredHookHandler(handlers, "subagent_spawning");
+  return await handler(event, {});
+}
+
+function expectSubagentHookError(result: unknown): { status: "error"; error: string } {
+  expect((result as { status?: unknown } | undefined)?.status).toBe("error");
+  const error = (result as { error?: unknown } | undefined)?.error;
+  expect(typeof error).toBe("string");
+  return result as { status: "error"; error: string };
+}
+
+async function expectSubagentSpawningError(params?: {
+  config?: Record<string, unknown>;
+  errorContains?: string;
+  event?: ReturnType<typeof createSpawnEvent>;
+}) {
+  const result = await runSubagentSpawning(params?.config, params?.event);
+  expect(hookMocks.autoBindSpawnedDiscordSubagent).not.toHaveBeenCalled();
+  const errorResult = expectSubagentHookError(result);
+  if (params?.errorContains) {
+    expect(errorResult.error).toContain(params.errorContains);
+  }
+}
+
+describe("discord subagent hook handlers", () => {
+  beforeAll(async () => {
+    ({ registerDiscordSubagentHooks } = await import("../subagent-hooks-api.js"));
+  });
+
+  beforeEach(() => {
+    hookMocks.resolveDiscordAccount.mockClear();
+    hookMocks.resolveDiscordAccount.mockImplementation(hookMocks.resolveDiscordAccountImpl);
+    hookMocks.autoBindSpawnedDiscordSubagent.mockClear();
+    hookMocks.listThreadBindingsBySessionKey.mockClear();
+    hookMocks.unbindThreadBindingsBySessionKey.mockClear();
+  });
+
+  it("binds thread routing on subagent_spawning", async () => {
+    const config = {
+      channels: {
+        discord: {
+          threadBindings: {
+            spawnSessions: true,
+          },
+        },
+      },
+    };
+    const handlers = registerHandlersForTest(config);
+    const handler = getRequiredHookHandler(handlers, "subagent_spawning");
+
+    const result = await handler(createSpawnEvent(), {});
+
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).toHaveBeenCalledTimes(1);
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).toHaveBeenCalledWith({
+      cfg: config,
+      accountId: "work",
+      channel: "discord",
+      to: "channel:123",
+      threadId: "456",
+      childSessionKey: "agent:main:subagent:child",
+      agentId: "main",
+      label: "banana",
+      boundBy: "system",
+    });
+    expect(result).toMatchObject({
+      status: "ok",
+      threadBindingReady: true,
+      deliveryOrigin: {
+        channel: "discord",
+        accountId: "work",
+        to: "channel:thread-1",
+        threadId: "thread-1",
+      },
+    });
+  });
+
+  it("returns error when thread-bound subagent spawn is disabled", async () => {
+    await expectSubagentSpawningError({
+      config: {
+        channels: {
+          discord: {
+            threadBindings: {
+              spawnSessions: false,
+            },
+          },
+        },
+      },
+      errorContains: "spawnSessions=true",
+    });
+  });
+
+  it("honors defaultAccount policy when requester omits accountId", async () => {
+    const config = {
+      channels: {
+        discord: {
+          defaultAccount: "work",
+          threadBindings: {
+            spawnSessions: true,
+          },
+          accounts: {
+            work: {
+              threadBindings: {
+                spawnSessions: false,
+              },
+            },
+          },
+        },
+      },
+    };
+    await expectSubagentSpawningError({
+      config,
+      event: createSpawnEvent({
+        requester: {
+          accountId: undefined,
+          channel: "discord",
+          to: "channel:123",
+          threadId: undefined,
+        },
+      }),
+      errorContains: "spawnSessions=true",
+    });
+    expect(hookMocks.resolveDiscordAccount).toHaveBeenCalledWith({
+      cfg: config,
+      accountId: undefined,
+    });
+  });
+
+  it("returns error when global thread bindings are disabled", async () => {
+    await expectSubagentSpawningError({
+      config: {
+        session: {
+          threadBindings: {
+            enabled: false,
+          },
+        },
+        channels: {
+          discord: {
+            threadBindings: {
+              spawnSessions: true,
+            },
+          },
+        },
+      },
+      errorContains: "threadBindings.enabled=true",
+    });
+  });
+
+  it("allows account-level threadBindings.enabled to override global disable", async () => {
+    const result = await runSubagentSpawning({
+      session: {
+        threadBindings: {
+          enabled: false,
+        },
+      },
+      channels: {
+        discord: {
+          accounts: {
+            work: {
+              threadBindings: {
+                enabled: true,
+                spawnSessions: true,
+              },
+            },
+          },
+        },
+      },
+    });
+
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({
+      status: "ok",
+      threadBindingReady: true,
+      deliveryOrigin: {
+        channel: "discord",
+        accountId: "work",
+        to: "channel:thread-1",
+        threadId: "thread-1",
+      },
+    });
+  });
+
+  it("defaults thread-bound subagent spawn to enabled when unset", async () => {
+    const result = await runSubagentSpawning({
+      channels: {
+        discord: {
+          threadBindings: {},
+        },
+      },
+    });
+
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({
+      status: "ok",
+      threadBindingReady: true,
+      deliveryOrigin: {
+        channel: "discord",
+        accountId: "work",
+        to: "channel:thread-1",
+        threadId: "thread-1",
+      },
+    });
+  });
+
+  it("no-ops when thread binding is requested on non-discord channel", async () => {
+    const result = await runSubagentSpawning(
+      undefined,
+      createSpawnEvent({
+        requester: {
+          channel: "signal",
+          accountId: "",
+          to: "+123",
+          threadId: undefined,
+        },
+      }),
+    );
+
+    expect(hookMocks.autoBindSpawnedDiscordSubagent).not.toHaveBeenCalled();
+    expect(result).toBeUndefined();
+  });
+
+  it("returns error when thread bind fails", async () => {
+    hookMocks.autoBindSpawnedDiscordSubagent.mockResolvedValueOnce(null);
+    const result = await runSubagentSpawning();
+
+    const errorResult = expectSubagentHookError(result);
+    expect(errorResult.error).toMatch(/unable to create or bind/i);
+  });
+
+  it("unbinds thread routing on subagent_ended", async () => {
+    const handlers = registerHandlersForTest();
+    const handler = getRequiredHookHandler(handlers, "subagent_ended");
+
+    await handler(
+      {
+        targetSessionKey: "agent:main:subagent:child",
+        targetKind: "subagent",
+        reason: "subagent-complete",
+        sendFarewell: true,
+        accountId: "work",
+      },
+      {},
+    );
+
+    expect(hookMocks.unbindThreadBindingsBySessionKey).toHaveBeenCalledTimes(1);
+    expect(hookMocks.unbindThreadBindingsBySessionKey).toHaveBeenCalledWith({
+      targetSessionKey: "agent:main:subagent:child",
+      accountId: "work",
+      targetKind: "subagent",
+      reason: "subagent-complete",
+      sendFarewell: true,
+    });
+  });
+
+  it("resolves delivery target from matching bound thread", async () => {
+    hookMocks.listThreadBindingsBySessionKey.mockReturnValueOnce([
+      { accountId: "work", threadId: "777" },
+    ]);
+    const result = await resolveSubagentDeliveryTargetForTest({
+      channel: "discord",
+      accountId: "work",
+      to: "channel:123",
+      threadId: "777",
+    });
+
+    expect(hookMocks.listThreadBindingsBySessionKey).toHaveBeenCalledWith({
+      targetSessionKey: "agent:main:subagent:child",
+      accountId: "work",
+      targetKind: "subagent",
+    });
+    expect(result).toEqual({
+      origin: {
+        channel: "discord",
+        accountId: "work",
+        to: "channel:777",
+        threadId: "777",
+      },
+    });
+  });
+
+  it("keeps original routing when delivery target is ambiguous", async () => {
+    hookMocks.listThreadBindingsBySessionKey.mockReturnValueOnce([
+      { accountId: "work", threadId: "777" },
+      { accountId: "work", threadId: "888" },
+    ]);
+    const result = await resolveSubagentDeliveryTargetForTest({
+      channel: "discord",
+      accountId: "work",
+      to: "channel:123",
+    });
+
+    expect(result).toBeUndefined();
+  });
+});