ACP: add persistent Discord channel and Telegram topic bindings (#34873)

* docs: add ACP persistent binding experiment plan * docs: align ACP persistent binding spec to channel-local config * docs: scope Telegram ACP bindings to forum topics only * docs: lock bound /new and /reset behavior to in-place ACP reset * ACP: add persistent discord/telegram conversation bindings * ACP: fix persistent binding reuse and discord thread parent context * docs: document channel-specific persistent ACP bindings * ACP: split persistent bindings and share conversation id helpers * ACP: defer configured binding init until preflight passes * ACP: fix discord thread parent fallback and explicit disable inheritance * ACP: keep bound /new and /reset in-place * ACP: honor configured bindings in native command flows * ACP: avoid configured fallback after runtime bind failure * docs: refine ACP bindings experiment config examples * acp: cut over to typed top-level persistent bindings * ACP bindings: harden reset recovery and native command auth * Docs: add ACP bound command auth proposal * Tests: normalize i18n registry zh-CN assertion encoding * ACP bindings: address review findings for reset and fallback routing * ACP reset: gate hooks on success and preserve /new arguments * ACP bindings: fix auth and binding-priority review findings * Telegram ACP: gate ensure on auth and accepted messages * ACP bindings: fix session-key precedence and unavailable handling * ACP reset/native commands: honor fallback targets and abort on bootstrap failure * Config schema: validate ACP binding channel and Telegram topic IDs * Discord ACP: apply configured DM bindings to native commands * ACP reset tails: dispatch through ACP after command handling * ACP tails/native reset auth: fix target dispatch and restore full auth * ACP reset detection: fallback to active ACP keys for DM contexts * Tests: type runTurn mock input in ACP dispatch test * ACP: dedup binding route bootstrap and reset target resolution * reply: align ACP reset hooks with bound session key * docs: replace personal discord ids with placeholders * fix: add changelog entry for ACP persistent bindings (#34873) (thanks @dutifulbob) --------- Co-authored-by: Onur <2453968+osolmaz@users.noreply.github.com>
2026-05-09 02:48:27 +00:00 · 2026-03-05 09:38:12 +01:00
parent 2c8ee593b9
commit 6a705a37f2
50 changed files with 4830 additions and 186 deletions
--- a/src/discord/monitor/message-handler.preflight.acp-bindings.test.ts
+++ b/src/discord/monitor/message-handler.preflight.acp-bindings.test.ts
@@ -0,0 +1,176 @@
+import { ChannelType } from "@buape/carbon";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const ensureConfiguredAcpBindingSessionMock = vi.hoisted(() => vi.fn());
+const resolveConfiguredAcpBindingRecordMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../../acp/persistent-bindings.js", () => ({
+  ensureConfiguredAcpBindingSession: (...args: unknown[]) =>
+    ensureConfiguredAcpBindingSessionMock(...args),
+  resolveConfiguredAcpBindingRecord: (...args: unknown[]) =>
+    resolveConfiguredAcpBindingRecordMock(...args),
+}));
+
+import { __testing as sessionBindingTesting } from "../../infra/outbound/session-binding-service.js";
+import { preflightDiscordMessage } from "./message-handler.preflight.js";
+import { createNoopThreadBindingManager } from "./thread-bindings.js";
+
+const GUILD_ID = "guild-1";
+const CHANNEL_ID = "channel-1";
+
+function createConfiguredDiscordBinding() {
+  return {
+    spec: {
+      channel: "discord",
+      accountId: "default",
+      conversationId: CHANNEL_ID,
+      agentId: "codex",
+      mode: "persistent",
+    },
+    record: {
+      bindingId: "config:acp:discord:default:channel-1",
+      targetSessionKey: "agent:codex:acp:binding:discord:default:abc123",
+      targetKind: "session",
+      conversation: {
+        channel: "discord",
+        accountId: "default",
+        conversationId: CHANNEL_ID,
+      },
+      status: "active",
+      boundAt: 0,
+      metadata: {
+        source: "config",
+        mode: "persistent",
+        agentId: "codex",
+      },
+    },
+  } as const;
+}
+
+function createBasePreflightParams(overrides?: Record<string, unknown>) {
+  const message = {
+    id: "m-1",
+    content: "<@bot-1> hello",
+    timestamp: new Date().toISOString(),
+    channelId: CHANNEL_ID,
+    attachments: [],
+    mentionedUsers: [{ id: "bot-1" }],
+    mentionedRoles: [],
+    mentionedEveryone: false,
+    author: {
+      id: "user-1",
+      bot: false,
+      username: "alice",
+    },
+  } as unknown as import("@buape/carbon").Message;
+
+  const client = {
+    fetchChannel: async (channelId: string) => {
+      if (channelId === CHANNEL_ID) {
+        return {
+          id: CHANNEL_ID,
+          type: ChannelType.GuildText,
+          name: "general",
+        };
+      }
+      return null;
+    },
+  } as unknown as import("@buape/carbon").Client;
+
+  return {
+    cfg: {
+      session: {
+        mainKey: "main",
+        scope: "per-sender",
+      },
+    } as import("../../config/config.js").OpenClawConfig,
+    discordConfig: {
+      allowBots: true,
+    } as NonNullable<import("../../config/config.js").OpenClawConfig["channels"]>["discord"],
+    accountId: "default",
+    token: "token",
+    runtime: {} as import("../../runtime.js").RuntimeEnv,
+    botUserId: "bot-1",
+    guildHistories: new Map(),
+    historyLimit: 0,
+    mediaMaxBytes: 1_000_000,
+    textLimit: 2_000,
+    replyToMode: "all",
+    dmEnabled: true,
+    groupDmEnabled: true,
+    ackReactionScope: "direct",
+    groupPolicy: "open",
+    threadBindings: createNoopThreadBindingManager("default"),
+    data: {
+      channel_id: CHANNEL_ID,
+      guild_id: GUILD_ID,
+      guild: {
+        id: GUILD_ID,
+        name: "Guild One",
+      },
+      author: message.author,
+      message,
+    } as unknown as import("./listeners.js").DiscordMessageEvent,
+    client,
+    ...overrides,
+  } satisfies Parameters<typeof preflightDiscordMessage>[0];
+}
+
+describe("preflightDiscordMessage configured ACP bindings", () => {
+  beforeEach(() => {
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+    ensureConfiguredAcpBindingSessionMock.mockReset();
+    resolveConfiguredAcpBindingRecordMock.mockReset();
+    resolveConfiguredAcpBindingRecordMock.mockReturnValue(createConfiguredDiscordBinding());
+    ensureConfiguredAcpBindingSessionMock.mockResolvedValue({
+      ok: true,
+      sessionKey: "agent:codex:acp:binding:discord:default:abc123",
+    });
+  });
+
+  it("does not initialize configured ACP bindings for rejected messages", async () => {
+    const result = await preflightDiscordMessage(
+      createBasePreflightParams({
+        guildEntries: {
+          [GUILD_ID]: {
+            id: GUILD_ID,
+            channels: {
+              [CHANNEL_ID]: {
+                allow: true,
+                enabled: false,
+              },
+            },
+          },
+        },
+      }),
+    );
+
+    expect(result).toBeNull();
+    expect(resolveConfiguredAcpBindingRecordMock).toHaveBeenCalledTimes(1);
+    expect(ensureConfiguredAcpBindingSessionMock).not.toHaveBeenCalled();
+  });
+
+  it("initializes configured ACP bindings only after preflight accepts the message", async () => {
+    const result = await preflightDiscordMessage(
+      createBasePreflightParams({
+        guildEntries: {
+          [GUILD_ID]: {
+            id: GUILD_ID,
+            channels: {
+              [CHANNEL_ID]: {
+                allow: true,
+                enabled: true,
+                requireMention: false,
+              },
+            },
+          },
+        },
+      }),
+    );
+
+    expect(result).not.toBeNull();
+    expect(resolveConfiguredAcpBindingRecordMock).toHaveBeenCalledTimes(1);
+    expect(ensureConfiguredAcpBindingSessionMock).toHaveBeenCalledTimes(1);
+    expect(result?.boundSessionKey).toBe("agent:codex:acp:binding:discord:default:abc123");
+  });
+});
--- a/src/discord/monitor/message-handler.preflight.ts
+++ b/src/discord/monitor/message-handler.preflight.ts
@@ -1,4 +1,8 @@
 import { ChannelType, MessageType, type User } from "@buape/carbon";
+import {
+  ensureConfiguredAcpRouteReady,
+  resolveConfiguredAcpRoute,
+} from "../../acp/persistent-bindings.route.js";
 import { hasControlCommand } from "../../auto-reply/command-detection.js";
 import { shouldHandleTextCommands } from "../../auto-reply/commands-registry.js";
 import {
@@ -328,8 +332,9 @@ export async function preflightDiscordMessage(
  const memberRoleIds = Array.isArray(params.data.rawMember?.roles)
    ? params.data.rawMember.roles.map((roleId: string) => String(roleId))
    : [];
+  const freshCfg = loadConfig();
  const route = resolveAgentRoute({
-    cfg: loadConfig(),
+    cfg: freshCfg,
    channel: "discord",
    accountId: params.accountId,
    guildId: params.data.guild_id ?? undefined,
@@ -342,13 +347,27 @@ export async function preflightDiscordMessage(
    parentPeer: earlyThreadParentId ? { kind: "channel", id: earlyThreadParentId } : undefined,
  });
  let threadBinding: SessionBindingRecord | undefined;
-  if (earlyThreadChannel) {
-    threadBinding =
-      getSessionBindingService().resolveByConversation({
-        channel: "discord",
-        accountId: params.accountId,
-        conversationId: messageChannelId,
-      }) ?? undefined;
+  threadBinding =
+    getSessionBindingService().resolveByConversation({
+      channel: "discord",
+      accountId: params.accountId,
+      conversationId: messageChannelId,
+      parentConversationId: earlyThreadParentId,
+    }) ?? undefined;
+  const configuredRoute =
+    threadBinding == null
+      ? resolveConfiguredAcpRoute({
+          cfg: freshCfg,
+          route,
+          channel: "discord",
+          accountId: params.accountId,
+          conversationId: messageChannelId,
+          parentConversationId: earlyThreadParentId,
+        })
+      : null;
+  const configuredBinding = configuredRoute?.configuredBinding ?? null;
+  if (!threadBinding && configuredBinding) {
+    threadBinding = configuredBinding.record;
  }
  if (
    shouldIgnoreBoundThreadWebhookMessage({
@@ -368,8 +387,9 @@ export async function preflightDiscordMessage(
        ...route,
        sessionKey: boundSessionKey,
        agentId: boundAgentId ?? route.agentId,
+        matchedBy: "binding.channel" as const,
      }
-    : route;
+    : (configuredRoute?.route ?? route);
  const isBoundThreadSession = Boolean(boundSessionKey && earlyThreadChannel);
  if (
    isBoundThreadBotSystemMessage({
@@ -739,6 +759,18 @@ export async function preflightDiscordMessage(
    logVerbose(`discord: drop message ${message.id} (empty content)`);
    return null;
  }
+  if (configuredBinding) {
+    const ensured = await ensureConfiguredAcpRouteReady({
+      cfg: freshCfg,
+      configuredBinding,
+    });
+    if (!ensured.ok) {
+      logVerbose(
+        `discord: configured ACP binding unavailable for channel ${configuredBinding.spec.conversationId}: ${ensured.error}`,
+      );
+      return null;
+    }
+  }

  logDebug(
    `[discord-preflight] success: route=${effectiveRoute.agentId} sessionKey=${effectiveRoute.sessionKey}`,
--- a/src/discord/monitor/native-command.plugin-dispatch.test.ts
+++ b/src/discord/monitor/native-command.plugin-dispatch.test.ts
@@ -7,10 +7,32 @@ import * as pluginCommandsModule from "../../plugins/commands.js";
 import { createDiscordNativeCommand } from "./native-command.js";
 import { createNoopThreadBindingManager } from "./thread-bindings.js";

+type ResolveConfiguredAcpBindingRecordFn =
+  typeof import("../../acp/persistent-bindings.js").resolveConfiguredAcpBindingRecord;
+type EnsureConfiguredAcpBindingSessionFn =
+  typeof import("../../acp/persistent-bindings.js").ensureConfiguredAcpBindingSession;
+
+const persistentBindingMocks = vi.hoisted(() => ({
+  resolveConfiguredAcpBindingRecord: vi.fn<ResolveConfiguredAcpBindingRecordFn>(() => null),
+  ensureConfiguredAcpBindingSession: vi.fn<EnsureConfiguredAcpBindingSessionFn>(async () => ({
+    ok: true,
+    sessionKey: "agent:codex:acp:binding:discord:default:seed",
+  })),
+}));
+
+vi.mock("../../acp/persistent-bindings.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../acp/persistent-bindings.js")>();
+  return {
+    ...actual,
+    resolveConfiguredAcpBindingRecord: persistentBindingMocks.resolveConfiguredAcpBindingRecord,
+    ensureConfiguredAcpBindingSession: persistentBindingMocks.ensureConfiguredAcpBindingSession,
+  };
+});
+
 type MockCommandInteraction = {
  user: { id: string; username: string; globalName: string };
  channel: { type: ChannelType; id: string };
-  guild: null;
+  guild: { id: string; name?: string } | null;
  rawData: { id: string; member: { roles: string[] } };
  options: {
    getString: ReturnType<typeof vi.fn>;
@@ -22,7 +44,13 @@ type MockCommandInteraction = {
  client: object;
 };

-function createInteraction(): MockCommandInteraction {
+function createInteraction(params?: {
+  channelType?: ChannelType;
+  channelId?: string;
+  guildId?: string;
+  guildName?: string;
+}): MockCommandInteraction {
+  const guild = params?.guildId ? { id: params.guildId, name: params.guildName } : null;
  return {
    user: {
      id: "owner",
@@ -30,10 +58,10 @@ function createInteraction(): MockCommandInteraction {
      globalName: "Tester",
    },
    channel: {
-      type: ChannelType.DM,
-      id: "dm-1",
+      type: params?.channelType ?? ChannelType.DM,
+      id: params?.channelId ?? "dm-1",
    },
-    guild: null,
+    guild,
    rawData: {
      id: "interaction-1",
      member: { roles: [] },
@@ -62,6 +90,13 @@ function createConfig(): OpenClawConfig {
 describe("Discord native plugin command dispatch", () => {
  beforeEach(() => {
    vi.restoreAllMocks();
+    persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockReset();
+    persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockReturnValue(null);
+    persistentBindingMocks.ensureConfiguredAcpBindingSession.mockReset();
+    persistentBindingMocks.ensureConfiguredAcpBindingSession.mockResolvedValue({
+      ok: true,
+      sessionKey: "agent:codex:acp:binding:discord:default:seed",
+    });
  });

  it("executes matched plugin commands directly without invoking the agent dispatcher", async () => {
@@ -110,4 +145,192 @@ describe("Discord native plugin command dispatch", () => {
      expect.objectContaining({ content: "direct plugin output" }),
    );
  });
+
+  it("routes native slash commands through configured ACP Discord channel bindings", async () => {
+    const guildId = "1459246755253325866";
+    const channelId = "1478836151241412759";
+    const boundSessionKey = "agent:codex:acp:binding:discord:default:feedface";
+    const cfg = {
+      commands: {
+        useAccessGroups: false,
+      },
+      bindings: [
+        {
+          type: "acp",
+          agentId: "codex",
+          match: {
+            channel: "discord",
+            accountId: "default",
+            peer: { kind: "channel", id: channelId },
+          },
+          acp: {
+            mode: "persistent",
+          },
+        },
+      ],
+    } as OpenClawConfig;
+    const commandSpec: NativeCommandSpec = {
+      name: "status",
+      description: "Status",
+      acceptsArgs: false,
+    };
+    const command = createDiscordNativeCommand({
+      command: commandSpec,
+      cfg,
+      discordConfig: cfg.channels?.discord ?? {},
+      accountId: "default",
+      sessionPrefix: "discord:slash",
+      ephemeralDefault: true,
+      threadBindings: createNoopThreadBindingManager("default"),
+    });
+    const interaction = createInteraction({
+      channelType: ChannelType.GuildText,
+      channelId,
+      guildId,
+      guildName: "Ops",
+    });
+
+    persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockReturnValue({
+      spec: {
+        channel: "discord",
+        accountId: "default",
+        conversationId: channelId,
+        agentId: "codex",
+        mode: "persistent",
+      },
+      record: {
+        bindingId: "config:acp:discord:default:1478836151241412759",
+        targetSessionKey: boundSessionKey,
+        targetKind: "session",
+        conversation: {
+          channel: "discord",
+          accountId: "default",
+          conversationId: channelId,
+        },
+        status: "active",
+        boundAt: 0,
+      },
+    });
+    persistentBindingMocks.ensureConfiguredAcpBindingSession.mockResolvedValue({
+      ok: true,
+      sessionKey: boundSessionKey,
+    });
+
+    vi.spyOn(pluginCommandsModule, "matchPluginCommand").mockReturnValue(null);
+    const dispatchSpy = vi
+      .spyOn(dispatcherModule, "dispatchReplyWithDispatcher")
+      .mockResolvedValue({
+        counts: {
+          final: 1,
+          block: 0,
+          tool: 0,
+        },
+      } as never);
+
+    await (command as { run: (interaction: unknown) => Promise<void> }).run(interaction as unknown);
+
+    expect(dispatchSpy).toHaveBeenCalledTimes(1);
+    const dispatchCall = dispatchSpy.mock.calls[0]?.[0] as {
+      ctx?: { SessionKey?: string; CommandTargetSessionKey?: string };
+    };
+    expect(dispatchCall.ctx?.SessionKey).toBe(boundSessionKey);
+    expect(dispatchCall.ctx?.CommandTargetSessionKey).toBe(boundSessionKey);
+    expect(persistentBindingMocks.resolveConfiguredAcpBindingRecord).toHaveBeenCalledTimes(1);
+    expect(persistentBindingMocks.ensureConfiguredAcpBindingSession).toHaveBeenCalledTimes(1);
+  });
+
+  it("routes Discord DM native slash commands through configured ACP bindings", async () => {
+    const channelId = "dm-1";
+    const boundSessionKey = "agent:codex:acp:binding:discord:default:dmfeedface";
+    const cfg = {
+      commands: {
+        useAccessGroups: false,
+      },
+      bindings: [
+        {
+          type: "acp",
+          agentId: "codex",
+          match: {
+            channel: "discord",
+            accountId: "default",
+            peer: { kind: "direct", id: channelId },
+          },
+          acp: {
+            mode: "persistent",
+          },
+        },
+      ],
+      channels: {
+        discord: {
+          dm: { enabled: true, policy: "open" },
+        },
+      },
+    } as OpenClawConfig;
+    const commandSpec: NativeCommandSpec = {
+      name: "status",
+      description: "Status",
+      acceptsArgs: false,
+    };
+    const command = createDiscordNativeCommand({
+      command: commandSpec,
+      cfg,
+      discordConfig: cfg.channels?.discord ?? {},
+      accountId: "default",
+      sessionPrefix: "discord:slash",
+      ephemeralDefault: true,
+      threadBindings: createNoopThreadBindingManager("default"),
+    });
+    const interaction = createInteraction({
+      channelType: ChannelType.DM,
+      channelId,
+    });
+
+    persistentBindingMocks.resolveConfiguredAcpBindingRecord.mockReturnValue({
+      spec: {
+        channel: "discord",
+        accountId: "default",
+        conversationId: channelId,
+        agentId: "codex",
+        mode: "persistent",
+      },
+      record: {
+        bindingId: "config:acp:discord:default:dm-1",
+        targetSessionKey: boundSessionKey,
+        targetKind: "session",
+        conversation: {
+          channel: "discord",
+          accountId: "default",
+          conversationId: channelId,
+        },
+        status: "active",
+        boundAt: 0,
+      },
+    });
+    persistentBindingMocks.ensureConfiguredAcpBindingSession.mockResolvedValue({
+      ok: true,
+      sessionKey: boundSessionKey,
+    });
+
+    vi.spyOn(pluginCommandsModule, "matchPluginCommand").mockReturnValue(null);
+    const dispatchSpy = vi
+      .spyOn(dispatcherModule, "dispatchReplyWithDispatcher")
+      .mockResolvedValue({
+        counts: {
+          final: 1,
+          block: 0,
+          tool: 0,
+        },
+      } as never);
+
+    await (command as { run: (interaction: unknown) => Promise<void> }).run(interaction as unknown);
+
+    expect(dispatchSpy).toHaveBeenCalledTimes(1);
+    const dispatchCall = dispatchSpy.mock.calls[0]?.[0] as {
+      ctx?: { SessionKey?: string; CommandTargetSessionKey?: string };
+    };
+    expect(dispatchCall.ctx?.SessionKey).toBe(boundSessionKey);
+    expect(dispatchCall.ctx?.CommandTargetSessionKey).toBe(boundSessionKey);
+    expect(persistentBindingMocks.resolveConfiguredAcpBindingRecord).toHaveBeenCalledTimes(1);
+    expect(persistentBindingMocks.ensureConfiguredAcpBindingSession).toHaveBeenCalledTimes(1);
+  });
 });
--- a/src/discord/monitor/native-command.ts
+++ b/src/discord/monitor/native-command.ts
@@ -14,6 +14,10 @@ import {
  type StringSelectMenuInteraction,
 } from "@buape/carbon";
 import { ApplicationCommandOptionType, ButtonStyle } from "discord-api-types/v10";
+import {
+  ensureConfiguredAcpRouteReady,
+  resolveConfiguredAcpRoute,
+} from "../../acp/persistent-bindings.route.js";
 import { resolveHumanDelayConfig } from "../../agents/identity.js";
 import { resolveChunkMode, resolveTextChunkLimit } from "../../auto-reply/chunk.js";
 import type {
@@ -1542,15 +1546,42 @@ async function dispatchDiscordCommandInteraction(params: {
    parentPeer: threadParentId ? { kind: "channel", id: threadParentId } : undefined,
  });
  const threadBinding = isThreadChannel ? threadBindings.getByThreadId(rawChannelId) : undefined;
-  const boundSessionKey = threadBinding?.targetSessionKey?.trim();
+  const configuredRoute =
+    threadBinding == null
+      ? resolveConfiguredAcpRoute({
+          cfg,
+          route,
+          channel: "discord",
+          accountId,
+          conversationId: channelId,
+          parentConversationId: threadParentId,
+        })
+      : null;
+  const configuredBinding = configuredRoute?.configuredBinding ?? null;
+  if (configuredBinding) {
+    const ensured = await ensureConfiguredAcpRouteReady({
+      cfg,
+      configuredBinding,
+    });
+    if (!ensured.ok) {
+      logVerbose(
+        `discord native command: configured ACP binding unavailable for channel ${configuredBinding.spec.conversationId}: ${ensured.error}`,
+      );
+      await respond("Configured ACP binding is unavailable right now. Please try again.");
+      return;
+    }
+  }
+  const configuredBoundSessionKey = configuredRoute?.boundSessionKey ?? "";
+  const boundSessionKey = threadBinding?.targetSessionKey?.trim() || configuredBoundSessionKey;
  const boundAgentId = boundSessionKey ? resolveAgentIdFromSessionKey(boundSessionKey) : undefined;
  const effectiveRoute = boundSessionKey
    ? {
        ...route,
        sessionKey: boundSessionKey,
        agentId: boundAgentId ?? route.agentId,
+        ...(configuredBinding ? { matchedBy: "binding.channel" as const } : {}),
      }
-    : route;
+    : (configuredRoute?.route ?? route);
  const conversationLabel = isDirectMessage ? (user.globalName ?? user.username) : channelId;
  const ownerAllowFrom = resolveDiscordOwnerAllowFrom({
    channelConfig,
@@ -1614,6 +1645,7 @@ async function dispatchDiscordCommandInteraction(params: {
    // preserve the real Discord target separately.
    OriginatingChannel: "discord" as const,
    OriginatingTo: isDirectMessage ? `user:${user.id}` : `channel:${channelId}`,
+    ThreadParentId: isThreadChannel ? threadParentId : undefined,
  });

  const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({