@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/gateway/inbound-pipeline.self-echo.test.ts

@@ -0,0 +1,218 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { RefIndexEntry } from "../ref/types.js";
+import type { InboundPipelineDeps } from "./inbound-context.js";
+import { buildInboundContext } from "./inbound-pipeline.js";
+import type { QueuedMessage } from "./message-queue.js";
+import type { GatewayAccount, GatewayPluginRuntime, ProcessedAttachments } from "./types.js";
+
+const getRefIndexMock = vi.hoisted(() => vi.fn<(refIdx: string) => RefIndexEntry | null>());
+const setRefIndexMock = vi.hoisted(() => vi.fn<(refIdx: string, entry: RefIndexEntry) => void>());
+const formatRefEntryForAgentMock = vi.hoisted(() => vi.fn<(entry: RefIndexEntry) => string>());
+const processAttachmentsMock = vi.hoisted(() =>
+  vi.fn<
+    (
+      attachments: QueuedMessage["attachments"],
+      ctx: { accountId: string; cfg: unknown; log?: unknown },
+    ) => Promise<ProcessedAttachments>
+  >(),
+);
+
+vi.mock("../ref/store.js", () => ({
+  getRefIndex: getRefIndexMock,
+  setRefIndex: setRefIndexMock,
+  formatRefEntryForAgent: formatRefEntryForAgentMock,
+}));
+
+vi.mock("./inbound-attachments.js", () => ({
+  processAttachments: processAttachmentsMock,
+}));
+
+const emptyProcessedAttachments: ProcessedAttachments = {
+  attachmentInfo: "",
+  imageUrls: [],
+  imageMediaTypes: [],
+  voiceAttachmentPaths: [],
+  voiceAttachmentUrls: [],
+  voiceAsrReferTexts: [],
+  voiceTranscripts: [],
+  voiceTranscriptSources: [],
+  attachmentLocalPaths: [],
+};
+
+const account: GatewayAccount = {
+  accountId: "qq-main",
+  appId: "app",
+  clientSecret: "secret",
+  markdownSupport: false,
+  config: {},
+};
+
+function makeRuntime(): GatewayPluginRuntime {
+  return {
+    channel: {
+      activity: { record: vi.fn() },
+      routing: {
+        resolveAgentRoute: vi.fn(() => ({
+          sessionKey: "qqbot:c2c:user-openid",
+          accountId: "qq-main",
+        })),
+      },
+      reply: {
+        dispatchReplyWithBufferedBlockDispatcher: vi.fn(),
+        finalizeInboundContext: vi.fn((fields: Record<string, unknown>) => fields),
+        formatInboundEnvelope: vi.fn(() => "formatted inbound"),
+        resolveEffectiveMessagesConfig: vi.fn(() => ({})),
+        resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+      },
+      session: {
+        resolveStorePath: vi.fn(() => "/tmp/openclaw/qqbot-sessions.json"),
+        recordInboundSession: vi.fn(async () => undefined),
+      },
+      turn: {
+        run: vi.fn(async (rawParams: unknown) => {
+          const params = rawParams as {
+            raw: unknown;
+            adapter: {
+              ingest: (raw: unknown) => unknown;
+              resolveTurn: (...args: unknown[]) => unknown;
+            };
+          };
+          const input = await params.adapter.ingest(params.raw);
+          const turn = (await params.adapter.resolveTurn(
+            input,
+            {
+              kind: "message",
+              canStartAgentTurn: true,
+            },
+            {},
+          )) as { runDispatch: () => Promise<unknown> };
+          return { dispatchResult: await turn.runDispatch() };
+        }),
+      },
+      text: {
+        chunkMarkdownText: (text: string) => [text],
+      },
+    },
+    tts: {
+      textToSpeech: vi.fn(),
+    },
+  };
+}
+
+function makeEvent(overrides: Partial<QueuedMessage> = {}): QueuedMessage {
+  return {
+    type: "c2c",
+    senderId: "user-openid",
+    messageId: "msg-1",
+    content: "hello",
+    timestamp: "2026-04-25T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+function makeDeps(overrides: Partial<InboundPipelineDeps> = {}): InboundPipelineDeps {
+  return {
+    account,
+    cfg: {},
+    log: { info: vi.fn(), error: vi.fn(), debug: vi.fn() },
+    runtime: makeRuntime(),
+    startTyping: vi.fn(async () => ({ keepAlive: null })),
+    adapters: {
+      history: {
+        recordPendingHistoryEntry: vi.fn(() => []),
+        buildPendingHistoryContext: vi.fn(() => ""),
+        clearPendingHistory: vi.fn(),
+      },
+      mentionGate: {
+        resolveInboundMentionDecision: vi.fn(() => ({
+          effectiveWasMentioned: false,
+          shouldSkip: false,
+          shouldBypassMention: false,
+          implicitMention: false,
+        })),
+      },
+      audioConvert: {
+        convertSilkToWav: vi.fn(async () => null),
+        isVoiceAttachment: vi.fn(() => false),
+        formatDuration: vi.fn(() => "0s"),
+      },
+      outboundAudio: {
+        audioFileToSilkBase64: vi.fn(async () => undefined),
+        isAudioFile: vi.fn(() => false),
+        shouldTranscodeVoice: vi.fn(() => false),
+        waitForFile: vi.fn(async () => 0),
+      },
+      commands: {
+        pluginVersion: "0.0.0-test",
+        resolveVersion: vi.fn(() => "0.0.0"),
+      },
+    },
+    ...overrides,
+  };
+}
+
+describe("buildInboundContext bot self-echo suppression", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    getRefIndexMock.mockReturnValue(null);
+    formatRefEntryForAgentMock.mockReturnValue("bot reply");
+    processAttachmentsMock.mockResolvedValue(emptyProcessedAttachments);
+  });
+
+  it("does not block inbound events whose current msgIdx matches this bot's outbound ref (self-echo handled upstream)", async () => {
+    getRefIndexMock.mockReturnValue({
+      content: "mirrored reply",
+      senderId: "qq-main",
+      timestamp: 1,
+      isBot: true,
+    });
+    const deps = makeDeps();
+
+    const inbound = await buildInboundContext(makeEvent({ msgIdx: "REF_BOT" }), deps);
+
+    // Self-echo suppression is handled by the gateway layer upstream;
+    // buildInboundContext no longer short-circuits on msgIdx match.
+    expect(inbound.blocked).toBe(false);
+    expect(deps.startTyping).toHaveBeenCalledTimes(1);
+    expect(processAttachmentsMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not block a user message that quotes a bot-authored ref", async () => {
+    getRefIndexMock.mockReturnValue({
+      content: "previous bot reply",
+      senderId: "qq-main",
+      timestamp: 1,
+      isBot: true,
+    });
+    const deps = makeDeps();
+
+    const inbound = await buildInboundContext(makeEvent({ refMsgIdx: "REF_BOT" }), deps);
+
+    expect(getRefIndexMock).toHaveBeenCalledWith("REF_BOT");
+    expect(formatRefEntryForAgentMock).toHaveBeenCalled();
+    expect(inbound.blocked).toBe(false);
+    expect(inbound.replyTo).toMatchObject({
+      id: "REF_BOT",
+      body: "bot reply",
+      isQuote: true,
+    });
+    expect(deps.startTyping).toHaveBeenCalledTimes(1);
+    expect(processAttachmentsMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not block matching refs from another QQ Bot account", async () => {
+    getRefIndexMock.mockReturnValue({
+      content: "other bot reply",
+      senderId: "qq-other",
+      timestamp: 1,
+      isBot: true,
+    });
+    const deps = makeDeps();
+
+    const inbound = await buildInboundContext(makeEvent({ msgIdx: "REF_BOT" }), deps);
+
+    expect(inbound.blocked).toBe(false);
+    expect(deps.startTyping).toHaveBeenCalledTimes(1);
+    expect(processAttachmentsMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/engine/gateway/inbound-pipeline.ts

@@ -0,0 +1,235 @@
+/**
+ * Inbound pipeline — compose stages into a single
+ * {@link buildInboundContext} call.
+ *
+ * The pipeline stays intentionally thin: all real logic lives in
+ * `./stages/*`. Reading this file top-to-bottom should be enough to
+ * understand the full inbound path.
+ *
+ * Stage order:
+ *   1. access      — route + access control (early return on block)
+ *   2. attachments — download + STT + image metadata
+ *   3. typing      — start the typing indicator (awaited before refIdx write)
+ *   4. content     — parseFaceTags + voice text + attachment info + mention cleanup
+ *   5. quote       — resolve `refMsgIdx` three ways
+ *   6. refIdx      — cache the current message so future quotes work
+ *   7. group gate  — @mention / ignoreOther / activation / command bypass
+ *                    (early return on skip, history already recorded)
+ *   8. envelope    — body / quotePart / dynamicCtx
+ *   9. assembly    — userMessage + agentBody (with pending-history prefix)
+ *  10. system      — final group system prompt composition
+ *  11. classify    — media classification (local vs remote; dedup voice)
+ *
+ * Returns a fully populated {@link InboundContext}. The gateway handler
+ * then branches on `blocked` / `skipped` to decide whether to dispatch
+ * outbound.
+ */
+
+import type { HistoryPort } from "../adapter/history.port.js";
+import type { HistoryEntry } from "../group/history.js";
+import { processAttachments } from "./inbound-attachments.js";
+import type { InboundContext, InboundPipelineDeps } from "./inbound-context.js";
+import type { QueuedMessage } from "./message-queue.js";
+import {
+  buildAgentBody,
+  buildBody,
+  buildDynamicCtx,
+  buildGroupSystemPrompt,
+  buildQuotePart,
+  buildSkippedInboundContext,
+  buildUserContent,
+  buildUserMessage,
+  classifyMedia,
+  resolveCommandAuthorized,
+  resolveQuote,
+  runAccessStage,
+  runGroupGateStage,
+  writeRefIndex,
+} from "./stages/index.js";
+
+/**
+ * Process a raw queued message through the full inbound pipeline.
+ *
+ * Returns an {@link InboundContext} with `blocked` / `skipped` set when
+ * the message should not reach the AI dispatcher.
+ */
+export async function buildInboundContext(
+  event: QueuedMessage,
+  deps: InboundPipelineDeps,
+): Promise<InboundContext> {
+  const { account, log } = deps;
+
+  // ---- 1. Access ----
+  const accessResult = runAccessStage(event, deps);
+  if (accessResult.kind === "block") {
+    return accessResult.context;
+  }
+  const { isGroupChat, peerId, qualifiedTarget, fromAddress, route, access } = accessResult;
+
+  // ---- 2. Typing indicator (async; awaited before refIdx write) ----
+  const typingPromise = deps.startTyping(event);
+
+  // ---- 3. Attachments ----
+  const processed = await processAttachments(event.attachments, {
+    accountId: account.accountId,
+    cfg: deps.cfg,
+    audioConvert: deps.adapters.audioConvert,
+    log,
+  });
+
+  // ---- 4. Content ----
+  const { parsedContent, userContent } = buildUserContent({
+    event,
+    attachmentInfo: processed.attachmentInfo,
+    voiceTranscripts: processed.voiceTranscripts,
+  });
+
+  // ---- 5. Quote ----
+  const replyTo = await resolveQuote(event, deps);
+
+  // ---- 6. RefIdx ----
+  const typingResult = await typingPromise;
+  writeRefIndex({
+    event,
+    parsedContent,
+    processed,
+    inputNotifyRefIdx: typingResult.refIdx,
+  });
+
+  // ---- 7. Group gate ----
+  let groupInfo: InboundContext["group"];
+  if (event.type === "group" && event.groupOpenid) {
+    const gateOutcome = runGroupGateStage({
+      event,
+      deps,
+      accountId: account.accountId,
+      agentId: route.agentId,
+      sessionKey: route.sessionKey,
+      userContent,
+      processedAttachments: processed,
+    });
+
+    if (gateOutcome.kind === "skip") {
+      typingResult.keepAlive?.stop();
+      return buildSkippedInboundContext({
+        event,
+        route,
+        isGroupChat: true,
+        peerId,
+        qualifiedTarget,
+        fromAddress,
+        group: gateOutcome.groupInfo,
+        skipReason: gateOutcome.skipReason,
+        access,
+        typing: { keepAlive: typingResult.keepAlive },
+        inputNotifyRefIdx: typingResult.refIdx,
+      });
+    }
+    groupInfo = gateOutcome.groupInfo;
+  }
+
+  // ---- 8. Envelope ----
+  const body = buildBody({
+    event,
+    deps,
+    userContent,
+    isGroupChat,
+    imageUrls: processed.imageUrls,
+  });
+  const quotePart = buildQuotePart(replyTo);
+  const media = classifyMedia(processed);
+  const dynamicCtx = buildDynamicCtx({
+    imageUrls: processed.imageUrls,
+    uniqueVoicePaths: media.uniqueVoicePaths,
+    uniqueVoiceUrls: media.uniqueVoiceUrls,
+    uniqueVoiceAsrReferTexts: media.uniqueVoiceAsrReferTexts,
+  });
+
+  // ---- 9. Assembly ----
+  const userMessage = buildUserMessage({
+    event,
+    userContent,
+    quotePart,
+    isGroupChat,
+    groupInfo,
+  });
+  const agentBody = buildAgentBody({
+    event,
+    userContent,
+    userMessage,
+    dynamicCtx,
+    isGroupChat,
+    groupInfo,
+    deps,
+  });
+
+  // ---- 10. System prompt ----
+  const systemPrompts: string[] = [];
+  if (account.systemPrompt) {
+    systemPrompts.push(account.systemPrompt);
+  }
+  const accountSystemInstruction = systemPrompts.length > 0 ? systemPrompts.join("\n") : "";
+  const groupSystemPrompt = buildGroupSystemPrompt(accountSystemInstruction, groupInfo);
+
+  // ---- 11. Authorization ----
+  const commandAuthorized = resolveCommandAuthorized(access);
+
+  return {
+    event,
+    route,
+    isGroupChat,
+    peerId,
+    qualifiedTarget,
+    fromAddress,
+    parsedContent,
+    userContent,
+    quotePart,
+    dynamicCtx,
+    userMessage,
+    agentBody,
+    body,
+    systemPrompts,
+    groupSystemPrompt,
+    attachments: processed,
+    localMediaPaths: media.localMediaPaths,
+    localMediaTypes: media.localMediaTypes,
+    remoteMediaUrls: media.remoteMediaUrls,
+    remoteMediaTypes: media.remoteMediaTypes,
+    uniqueVoicePaths: media.uniqueVoicePaths,
+    uniqueVoiceUrls: media.uniqueVoiceUrls,
+    uniqueVoiceAsrReferTexts: media.uniqueVoiceAsrReferTexts,
+    voiceMediaTypes: media.voiceMediaTypes,
+    hasAsrReferFallback: media.hasAsrReferFallback,
+    voiceTranscriptSources: media.voiceTranscriptSources,
+    replyTo,
+    commandAuthorized,
+    group: groupInfo,
+    blocked: false,
+    skipped: false,
+    accessDecision: access.decision,
+    typing: { keepAlive: typingResult.keepAlive },
+    inputNotifyRefIdx: typingResult.refIdx,
+  };
+}
+
+// ============ Public history-clear helper ============
+
+/**
+ * Clear a group's pending history buffer. Exposed so the gateway can
+ * call it in its `finally` block after a reply attempt.
+ */
+export function clearGroupPendingHistory(params: {
+  historyMap: Map<string, HistoryEntry[]> | undefined;
+  groupOpenid: string | undefined;
+  historyLimit: number;
+  historyPort: HistoryPort;
+}): void {
+  if (!params.historyMap || !params.groupOpenid) {
+    return;
+  }
+  params.historyPort.clearPendingHistory({
+    historyMap: params.historyMap,
+    historyKey: params.groupOpenid,
+    limit: params.historyLimit,
+  });
+}

package/src/engine/gateway/interaction-handler.ts

@@ -0,0 +1,220 @@
+/**
+ * INTERACTION_CREATE event handler.
+ *
+ * Handles three interaction branches:
+ *
+ * 1. **Config query**  (type=2001) — reads config, ACKs with `claw_cfg`.
+ * 2. **Config update** (type=2002) — writes config, ACKs with updated snapshot.
+ * 3. **Approval button** (other)   — ACKs, resolves approval via PlatformAdapter.
+ *
+ * Config query/update require `runtime.config`. When unavailable, those
+ * branches fall through to a bare ACK (backward-compatible).
+ */
+
+import { resolveQQBotEffectivePolicies } from "../access/resolve-policy.js";
+import { getPlatformAdapter } from "../adapter/index.js";
+import { parseApprovalButtonData } from "../approval/index.js";
+import { getPluginVersion, getFrameworkVersion } from "../commands/slash-commands-impl.js";
+import { resolveGroupConfig, resolveMentionPatterns } from "../config/group.js";
+import { resolveAccountBase } from "../config/resolve.js";
+import type { GroupActivationMode } from "../group/activation.js";
+import { accountToCreds, acknowledgeInteraction } from "../messaging/sender.js";
+import type { InteractionEvent, QQBotAccountConfigView } from "../types.js";
+import { InteractionType } from "./constants.js";
+import type { GatewayAccount, GatewayPluginRuntime, EngineLogger } from "./types.js";
+
+// ============ claw_cfg snapshot ============
+
+/**
+ * Build the canonical `claw_cfg` snapshot returned in interaction ACKs.
+ *
+ * Pure function — all resolution helpers live in engine/config/.
+ */
+function buildClawCfgSnapshot(
+  cfg: Record<string, unknown>,
+  accountId: string,
+  groupOpenid: string,
+  runtime: GatewayPluginRuntime,
+): Record<string, unknown> {
+  const groupCfg = groupOpenid ? resolveGroupConfig(cfg, groupOpenid, accountId) : null;
+  const accountBase = resolveAccountBase(cfg, accountId);
+  const acctCfg = accountBase.config as QQBotAccountConfigView;
+  const policies = resolveQQBotEffectivePolicies({
+    allowFrom: acctCfg.allowFrom,
+    groupAllowFrom: acctCfg.groupAllowFrom,
+    dmPolicy: acctCfg.dmPolicy,
+    groupPolicy: acctCfg.groupPolicy,
+  });
+
+  const requireMentionMode: GroupActivationMode =
+    (groupCfg?.requireMention ?? true) ? "mention" : "always";
+
+  const interactionAgentId = groupOpenid
+    ? (
+        runtime.channel.routing.resolveAgentRoute({
+          cfg,
+          channel: "qqbot",
+          accountId,
+          peer: { kind: "group", id: groupOpenid },
+        }) as { agentId?: string } | undefined
+      )?.agentId
+    : undefined;
+
+  return {
+    channel_type: "qqbot",
+    channel_ver: getPluginVersion(),
+    claw_type: "openclaw",
+    claw_ver: getFrameworkVersion(),
+    require_mention: requireMentionMode,
+    group_policy: policies.groupPolicy,
+    mention_patterns: resolveMentionPatterns(cfg, interactionAgentId).join(","),
+    online_state: "online",
+  };
+}
+
+// ============ Config update ============
+
+/** Apply a config-update interaction and return the updated claw_cfg. */
+async function applyConfigUpdate(
+  event: InteractionEvent,
+  accountId: string,
+  runtime: GatewayPluginRuntime,
+  log?: EngineLogger,
+): Promise<Record<string, unknown>> {
+  const configApi = runtime.config;
+  if (!configApi) {
+    throw new Error("runtime.config not available");
+  }
+
+  const resolved = event.data?.resolved as Record<string, unknown> | undefined;
+  const clawCfgUpdate = resolved?.claw_cfg as Record<string, unknown> | undefined;
+  const groupOpenid = event.group_openid ?? "";
+
+  const currentCfg = structuredClone(configApi.current());
+  let changed = false;
+
+  if (clawCfgUpdate?.require_mention !== undefined && groupOpenid) {
+    applyRequireMentionUpdate(currentCfg, accountId, groupOpenid, clawCfgUpdate);
+    changed = true;
+  }
+
+  if (changed) {
+    await configApi.replaceConfigFile({ nextConfig: currentCfg, afterWrite: { mode: "auto" } });
+    log?.info(
+      `Config updated via interaction ${event.id}: require_mention=${String(clawCfgUpdate?.require_mention)}, group=${groupOpenid}`,
+    );
+  }
+
+  const latestCfg = changed ? configApi.current() : currentCfg;
+  return buildClawCfgSnapshot(latestCfg, accountId, groupOpenid, runtime);
+}
+
+/** Mutate `cfg` in place to apply a require_mention update for a group. */
+function applyRequireMentionUpdate(
+  cfg: Record<string, unknown>,
+  accountId: string,
+  groupOpenid: string,
+  update: Record<string, unknown>,
+): void {
+  const requireMentionBool = update.require_mention === "mention";
+  const channels = (cfg.channels ?? {}) as Record<string, unknown>;
+  const qqbot = (channels.qqbot ?? {}) as Record<string, unknown>;
+
+  const isNamedAccount =
+    accountId !== "default" &&
+    Boolean((qqbot.accounts as Record<string, Record<string, unknown>> | undefined)?.[accountId]);
+
+  if (isNamedAccount) {
+    const accounts = (qqbot.accounts ?? {}) as Record<string, Record<string, unknown>>;
+    const acct = accounts[accountId] ?? {};
+    const groups = (acct.groups ?? {}) as Record<string, Record<string, unknown>>;
+    groups[groupOpenid] = { ...groups[groupOpenid], requireMention: requireMentionBool };
+    acct.groups = groups;
+    accounts[accountId] = acct;
+    qqbot.accounts = accounts;
+  } else {
+    const groups = (qqbot.groups ?? {}) as Record<string, Record<string, unknown>>;
+    groups[groupOpenid] = { ...groups[groupOpenid], requireMention: requireMentionBool };
+    qqbot.groups = groups;
+  }
+}
+
+// ============ Public factory ============
+
+/**
+ * Create the INTERACTION_CREATE event handler.
+ *
+ * Returns a fire-and-forget callback that `GatewayConnection` calls
+ * on every `action: "interaction"` dispatch result.
+ */
+export function createInteractionHandler(
+  account: GatewayAccount,
+  runtime: GatewayPluginRuntime,
+  log?: EngineLogger,
+): (event: InteractionEvent) => void {
+  return (event) => {
+    const creds = accountToCreds(account);
+    const type = event.data?.type;
+
+    // ---- Config query (type=2001) ----
+    if (type === InteractionType.CONFIG_QUERY && runtime.config) {
+      void handleWithAck(creds, event, log, "CONFIG_QUERY", () => {
+        const cfg = runtime.config!.current();
+        return buildClawCfgSnapshot(cfg, account.accountId, event.group_openid ?? "", runtime);
+      });
+      return;
+    }
+
+    // ---- Config update (type=2002) ----
+    if (type === InteractionType.CONFIG_UPDATE && runtime.config) {
+      void handleWithAck(creds, event, log, "CONFIG_UPDATE", () =>
+        applyConfigUpdate(event, account.accountId, runtime, log),
+      );
+      return;
+    }
+
+    // ---- Approval button / other ----
+    void acknowledgeInteraction(creds, event.id).catch((err) => {
+      log?.error(`Interaction ACK failed: ${err instanceof Error ? err.message : String(err)}`);
+    });
+
+    const parsed = parseApprovalButtonData(event.data?.resolved?.button_data ?? "");
+    if (!parsed) {
+      return;
+    }
+
+    const adapter = getPlatformAdapter();
+    if (!adapter.resolveApproval) {
+      log?.error("resolveApproval not available on PlatformAdapter");
+      return;
+    }
+
+    void adapter.resolveApproval(parsed.approvalId, parsed.decision).then((ok) => {
+      if (ok) {
+        log?.info(`Approval resolved: id=${parsed.approvalId}, decision=${parsed.decision}`);
+      } else {
+        log?.error(`Approval resolve failed: id=${parsed.approvalId}`);
+      }
+    });
+  };
+}
+
+// ============ Helpers ============
+
+/** Execute an async handler, ACK with the result, and handle errors. */
+async function handleWithAck(
+  creds: { appId: string; clientSecret: string },
+  event: InteractionEvent,
+  log: EngineLogger | undefined,
+  label: string,
+  handler: () => Record<string, unknown> | Promise<Record<string, unknown>>,
+): Promise<void> {
+  try {
+    const clawCfg = await handler();
+    await acknowledgeInteraction(creds, event.id, 0, { claw_cfg: clawCfg });
+    log?.info(`Interaction ACK (${label}) sent: ${event.id}`);
+  } catch (err) {
+    log?.error(`${label} interaction failed: ${err instanceof Error ? err.message : String(err)}`);
+    void acknowledgeInteraction(creds, event.id).catch(() => {});
+  }
+}