@soimy/dingtalk 3.6.10 → 3.7.0

package/src/{types.ts → platform/types.ts}

@@ -13,7 +13,7 @@ import type {
   ChannelAccountSnapshot as SDKChannelAccountSnapshot,
   ChannelGatewayContext as SDKChannelGatewayContext,
   ChannelLogSink as SDKChannelLogSink,
-} from "openclaw/plugin-sdk/channel-runtime";
+} from "openclaw/plugin-sdk/channel-contract";
 import type { ChannelPlugin as SDKChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk/core";
 import type { ChannelSetupWizard } from "openclaw/plugin-sdk/setup";
 import type { SecretInput } from "./secret-input";
@@ -23,8 +23,34 @@ export type AckReactionMode = "off" | "emoji" | "kaomoji";
 // explicit modes remain: "off" | "emoji" | "kaomoji".
 export type AckReactionConfigValue = string;
 export type CardStreamingMode = "off" | "answer" | "all";
+/** How tool-driven task-progress changes reach the card:
+ *  - `heartbeat` (default): coalesced into the 30s progress heartbeat
+ *  - `interval`: pushed on every correlated tool event, throttled by `cardStreamInterval` */
+export type CardTaskProgressRefresh = "heartbeat" | "interval";
 export type ContextVisibilityMode = "all" | "allowlist" | "allowlist_quote";
 
+/**
+ * Gateway RPC capability configuration (Issue #608, 问题 3).
+ * Aligns with the official connector's `tools: { docs, media }` gate shape.
+ * All capabilities default to enabled for backward compatibility.
+ */
+export interface DingTalkGatewayCapabilitiesConfig {
+  tools?: {
+    /** Enable `dingtalk.docs.*` and `dingtalk-connector.docs.*` Gateway RPCs (default: true) */
+    docs?: boolean;
+    /** Enable proactive-send Gateway RPCs: `dingtalk-connector.sendToUser/sendToGroup/send` (default: true) */
+    proactiveSend?: boolean;
+  };
+  /** Optional doc-space allowlist; when set, docs RPCs only accept these `spaceId` values */
+  docs?: {
+    allowedSpaceIds?: string[];
+  };
+  /** Optional proactive-send target allowlist; entries must be `user:*` or `group:*` */
+  send?: {
+    allowedTargets?: string[];
+  };
+}
+
 /**
  * DingTalk channel configuration (extends base OpenClaw config)
  */
@@ -79,10 +105,23 @@ export interface DingTalkConfig extends OpenClawConfig {
    *  - answer: stream answer text
    *  - all: stream answer + reasoning text */
   cardStreamingMode?: CardStreamingMode;
+  /** Internal derived flag, not a user-facing config key: whether
+   *  `cardStreamingMode` came from an explicit user setting instead of the
+   *  runtime default. Written by config normalization only. */
+  cardStreamingModeConfigured?: boolean;
   /** @deprecated Use `cardStreamingMode` instead. */
   cardRealTimeStream?: boolean;
   /** Throttle interval in ms for card stream updates (default 1000) */
   cardStreamInterval?: number;
+  /** Live "task in progress" block on AI cards for long-running tasks.
+   *  `true` forces it on, `false` forces it off; when unset it is on unless
+   *  `cardStreamingMode` is explicitly `"off"`. */
+  cardTaskProgress?: boolean;
+  /** How stage/step changes reach the progress block. `heartbeat` (default)
+   *  keeps the documented "once on appearance, then once per 30s" budget;
+   *  `interval` pushes on every correlated tool event, throttled by
+   *  `cardStreamInterval`, trading card updates for a fresher stage label. */
+  cardTaskProgressRefresh?: CardTaskProgressRefresh;
   /** AICard degrade duration in milliseconds after trigger errors (default 30m) */
   aicardDegradeMs?: number;
   /** Enable local learning loop (events/reflections/session notes/global rules) */
@@ -104,6 +143,8 @@ export interface DingTalkConfig extends OpenClawConfig {
     tokens?: boolean;
     dapiUsage?: boolean;
   };
+  /** Gateway RPC capability gates and allowlists (docs RPCs + proactive-send RPCs). Named `gatewayCapabilities` because host `OpenClawConfig` already owns `gateway` and `tools`, and a bare `capabilities` key would collide with this plugin's channel capabilities metadata. */
+  gatewayCapabilities?: DingTalkGatewayCapabilitiesConfig;
 }
 
 /**
@@ -159,10 +200,23 @@ export interface DingTalkChannelConfig {
    *  - answer: stream answer text
    *  - all: stream answer + reasoning text */
   cardStreamingMode?: CardStreamingMode;
+  /** Internal derived flag, not a user-facing config key: whether
+   *  `cardStreamingMode` came from an explicit user setting instead of the
+   *  runtime default. Written by config normalization only. */
+  cardStreamingModeConfigured?: boolean;
   /** @deprecated Use `cardStreamingMode` instead. */
   cardRealTimeStream?: boolean;
   /** Throttle interval in ms for card stream updates (default 1000) */
   cardStreamInterval?: number;
+  /** Live "task in progress" block on AI cards for long-running tasks.
+   *  `true` forces it on, `false` forces it off; when unset it is on unless
+   *  `cardStreamingMode` is explicitly `"off"`. */
+  cardTaskProgress?: boolean;
+  /** How stage/step changes reach the progress block. `heartbeat` (default)
+   *  keeps the documented "once on appearance, then once per 30s" budget;
+   *  `interval` pushes on every correlated tool event, throttled by
+   *  `cardStreamInterval`, trading card updates for a fresher stage label. */
+  cardTaskProgressRefresh?: CardTaskProgressRefresh;
   /** AICard degrade duration in milliseconds after trigger errors (default 30m) */
   aicardDegradeMs?: number;
   /** Enable local learning loop (events/reflections/session notes/global rules) */
@@ -175,6 +229,8 @@ export interface DingTalkChannelConfig {
   convertMarkdownTables?: boolean;
   /** @mention the sender after card finalization in group chats; value is the message text */
   cardAtSender?: string;
+  /** Gateway RPC capability gates and allowlists (docs RPCs + proactive-send RPCs). Named `gatewayCapabilities` because host `OpenClawConfig` already owns `gateway` and `tools`, and a bare `capabilities` key would collide with this plugin's channel capabilities metadata. */
+  gatewayCapabilities?: DingTalkGatewayCapabilitiesConfig;
 }
 
 /**
@@ -227,6 +283,17 @@ export interface DocInfo {
   updatedAt?: number | string;
 }
 
+/**
+ * Recursive element node of an interactiveCard `cardContent` payload.
+ * Real DingTalk quote callbacks carry card text as nested element trees
+ * (e.g. LIST -> RICHTEXT -> TEXT nodes) rather than a flat `text` field.
+ */
+export interface DingTalkCardContentNode {
+  elementType?: string;
+  value?: string;
+  children?: DingTalkCardContentNode[];
+}
+
 /**
  * DingTalk incoming message (Stream mode)
  */
@@ -252,9 +319,13 @@ export interface DingTalkInboundMessage {
       createdAt?: number;
       content?: {
         text?: string;
+        /** Quoted text message body in real payloads (`msgType: "text"`). */
+        content?: string;
         downloadCode?: string;
         fileName?: string;
         biz_custom_action_url?: string;
+        /** interactiveCard quoted content as nested element tree. */
+        cardContent?: DingTalkCardContentNode[];
         richText?: Array<{
           msgType?: string;
           type?: string;
@@ -415,7 +486,11 @@ export interface SendMessageOptions {
   /** Force markdown/text delivery even when messageType is "card". Bypasses card
    *  creation while preserving journal writes and other side-effects. */
   forceMarkdown?: boolean;
-  /** Allowed local roots for sandbox/container media path resolution. */
+  /**
+   * Host-provided allowlist of local media roots. When set, caller-supplied
+   * host paths whose canonical location is outside these roots are resolved
+   * through the runtime media bridge instead of being read directly.
+   */
   mediaLocalRoots?: string[];
 }
 

package/src/{http-client.ts → shared/http-client.ts}

@@ -10,9 +10,7 @@ type AxiosInstanceWithGuards = AxiosInstance & {
 // Centralize repo-level axios policy without mutating the global axios singleton
 // that third-party dependencies may also share.
 const httpClient = (
-  typeof axios?.create === "function"
-    ? axios.create({ timeout: DEFAULT_HTTP_TIMEOUT_MS })
-    : axios
+  typeof axios?.create === "function" ? axios.create({ timeout: DEFAULT_HTTP_TIMEOUT_MS }) : axios
 ) as AxiosInstanceWithGuards;
 
 httpClient.isAxiosError = axios.isAxiosError;

package/src/{persistence-store.ts → shared/persistence-store.ts}

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { Logger } from "./types";
+import type { Logger } from "../platform/types";
 
 type NamespaceFormat = "json";
 
@@ -71,7 +71,10 @@ function buildScopeSuffix(scope?: PersistenceScope): string {
   return `.${segments.join(".")}`;
 }
 
-export function resolveNamespacePath(namespace: string, options: ResolveNamespacePathOptions): string {
+export function resolveNamespacePath(
+  namespace: string,
+  options: ResolveNamespacePathOptions,
+): string {
   const format = options.format || "json";
   const baseDir = path.join(path.dirname(options.storePath), NAMESPACE_ROOT_DIR);
   const safeNamespace = sanitizeSegment(namespace.trim());
@@ -79,10 +82,7 @@ export function resolveNamespacePath(namespace: string, options: ResolveNamespac
   return path.join(baseDir, `${safeNamespace}${suffix}.${format}`);
 }
 
-export function readNamespaceJson<T>(
-  namespace: string,
-  options: ReadNamespaceJsonOptions<T>,
-): T {
+export function readNamespaceJson<T>(namespace: string, options: ReadNamespaceJsonOptions<T>): T {
   const filePath = resolveNamespacePath(namespace, options);
   try {
     if (!fs.existsSync(filePath)) {

package/src/{utils.ts → shared/utils.ts}

@@ -3,7 +3,7 @@ import * as fs from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { Logger, RetryOptions } from "./types";
+import type { Logger, RetryOptions } from "../platform/types";
 
 type PluginDebugLogParams = {
   accountId: string;
@@ -44,7 +44,11 @@ function formatPluginDebugDate(date: Date): string {
   return `${date.getFullYear()}-${padNumber(date.getMonth() + 1)}-${padNumber(date.getDate())}`;
 }
 
-function resolvePluginDebugLogFilePath(params: { storePath: string; accountId: string; date: Date }): string {
+function resolvePluginDebugLogFilePath(params: {
+  storePath: string;
+  accountId: string;
+  date: Date;
+}): string {
   return path.join(
     path.dirname(params.storePath),
     "logs",
@@ -58,7 +62,11 @@ function formatPluginDebugLine(params: { accountId: string; date: Date; message:
   return `[${formatPluginDebugTimestamp(params.date)}] [debug] [dingtalk] [account:${params.accountId}] ${params.message}`;
 }
 
-function buildPluginDebugWriterKey(params: { storePath: string; accountId: string; date: Date }): string {
+function buildPluginDebugWriterKey(params: {
+  storePath: string;
+  accountId: string;
+  date: Date;
+}): string {
   return JSON.stringify([params.storePath, params.accountId, formatPluginDebugDate(params.date)]);
 }
 
@@ -209,11 +217,7 @@ export function stringifyUnknown(value: unknown): string {
   if (typeof value === "string") {
     return value;
   }
-  if (
-    typeof value === "number" ||
-    typeof value === "boolean" ||
-    typeof value === "bigint"
-  ) {
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
     return String(value);
   }
   try {
@@ -292,7 +296,11 @@ export function formatDingTalkErrorPayload(payload: unknown): string {
   } catch {
     if (typeof payload === "string") {
       serialized = payload;
-    } else if (typeof payload === "number" || typeof payload === "boolean" || typeof payload === "bigint") {
+    } else if (
+      typeof payload === "number" ||
+      typeof payload === "boolean" ||
+      typeof payload === "bigint"
+    ) {
       serialized = `${payload}`;
     } else {
       serialized = "[unserializable-payload]";
@@ -318,7 +326,9 @@ export function formatDingTalkErrorPayloadLog(
   return `${prefix}[ErrorPayload][${scope}] ${formatDingTalkErrorPayload(payload)}`;
 }
 
-export function getProxyBypassOption(config?: { bypassProxyForSend?: boolean }): { proxy: false } | Record<string, never> {
+export function getProxyBypassOption(config?: {
+  bypassProxyForSend?: boolean;
+}): { proxy: false } | Record<string, never> {
   return config?.bypassProxyForSend ? { proxy: false } : {};
 }
 
@@ -445,7 +455,8 @@ export function formatDingTalkConnectionErrorLog(
       ? errRecord.dingtalkConnectionEndpoint
       : undefined;
 
-  const hasResponse = "response" in errRecord && errRecord.response !== null && errRecord.response !== undefined;
+  const hasResponse =
+    "response" in errRecord && errRecord.response !== null && errRecord.response !== undefined;
   if (!hasResponse && !endpoint && stage === scope) {
     return null;
   }
@@ -455,7 +466,8 @@ export function formatDingTalkConnectionErrorLog(
     parts.push(`endpoint=${endpoint}`);
   }
 
-  const response = (err as { response?: { status?: unknown; data?: unknown; headers?: unknown } }).response;
+  const response = (err as { response?: { status?: unknown; data?: unknown; headers?: unknown } })
+    .response;
   if (response) {
     if (response.status !== undefined && response.status !== null) {
       const statusText =
@@ -469,7 +481,12 @@ export function formatDingTalkConnectionErrorLog(
     }
 
     let requestId = getHeaderCaseInsensitive(response.headers, "x-acs-dingtalk-request-id");
-    if (!requestId && response.data && typeof response.data === "object" && !Array.isArray(response.data)) {
+    if (
+      !requestId &&
+      response.data &&
+      typeof response.data === "object" &&
+      !Array.isArray(response.data)
+    ) {
       const data = response.data as Record<string, unknown>;
       if (typeof data.requestId === "string") {
         requestId = data.requestId;

package/src/targeting/agent-name-matcher.ts

@@ -5,7 +5,7 @@
  */
 
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
-import type { AtMention, AgentNameMatch } from "../types";
+import type { AtMention, AgentNameMatch } from "../platform/types";
 
 interface AgentConfig {
   id: string;

package/src/targeting/agent-routing.ts

@@ -9,10 +9,10 @@
 
 import { maybeResolveTextAlias } from "openclaw/plugin-sdk/command-auth";
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
-import { resolveRobotCode } from "../config";
-import { parseLearnCommand } from "../learning-command-service";
-import { getDingTalkRuntime } from "../runtime";
-import { sendBySession } from "../send-service";
+import { parseLearnCommand } from "../command/learning-command-service";
+import { sendBySession } from "../messaging/send-service";
+import { resolveRobotCode } from "../platform/config";
+import { getDingTalkRuntime } from "../platform/runtime";
 import type {
   AgentNameMatch,
   DingTalkConfig,
@@ -21,10 +21,10 @@ import type {
   Logger,
   MessageContent,
   ResolvedDingTalkRoute,
-} from "../types";
-import { getErrorMessage } from "../utils";
+} from "../platform/types";
+import { getErrorMessage } from "../shared/utils";
 import { resolveAtAgents } from "./agent-name-matcher";
-import type { ResolvedDingTalkSessionPeer } from "../session-routing";
+import type { ResolvedDingTalkSessionPeer } from "./session-routing";
 
 export class HostRoutingHelperUnavailableError extends Error {
   constructor(

package/src/targeting/group-members-store.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { readNamespaceJson, writeNamespaceJsonAtomic } from "../persistence-store";
+import { readNamespaceJson, writeNamespaceJsonAtomic } from "../shared/persistence-store";
 
 const GROUP_MEMBERS_NAMESPACE = "members.group-roster";
 

package/src/{session-peer-store.ts → targeting/session-peer-store.ts}

@@ -1,4 +1,4 @@
-import { readNamespaceJson, writeNamespaceJsonAtomic } from "./persistence-store";
+import { readNamespaceJson, writeNamespaceJsonAtomic } from "../shared/persistence-store";
 
 const SESSION_PEER_OVERRIDE_NAMESPACE = "session-peer-overrides";
 
@@ -20,7 +20,11 @@ function readBucket(storePath: string, accountId: string): SessionPeerOverrideBu
   });
 }
 
-function writeBucket(storePath: string, accountId: string, bucket: SessionPeerOverrideBucket): void {
+function writeBucket(
+  storePath: string,
+  accountId: string,
+  bucket: SessionPeerOverrideBucket,
+): void {
   writeNamespaceJsonAtomic(SESSION_PEER_OVERRIDE_NAMESPACE, {
     storePath,
     scope: { accountId },
@@ -63,8 +67,9 @@ export function clearSessionPeerOverride(params: {
   const bucket = readBucket(params.storePath, params.accountId);
   const sourceKey = buildSourceKey(params.sourceKind, params.sourceId);
   const legacyKey = params.sourceKind === "group" ? params.sourceId : undefined;
-  const existed = Object.prototype.hasOwnProperty.call(bucket.peers, sourceKey)
-    || (legacyKey ? Object.prototype.hasOwnProperty.call(bucket.peers, legacyKey) : false);
+  const existed =
+    Object.prototype.hasOwnProperty.call(bucket.peers, sourceKey) ||
+    (legacyKey ? Object.prototype.hasOwnProperty.call(bucket.peers, legacyKey) : false);
   if (!existed) {
     return false;
   }

package/src/{session-routing.ts → targeting/session-routing.ts}

@@ -1,4 +1,4 @@
-import type { DingTalkConfig } from "./types";
+import type { DingTalkConfig } from "../platform/types";
 
 export interface ResolveDingTalkSessionPeerParams {
   isDirect: boolean;

package/src/targeting/target-directory-adapter.ts

@@ -1,8 +1,8 @@
 import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
 import type { ChannelDirectoryEntry } from "openclaw/plugin-sdk/directory-runtime";
-import { getConfig, stripTargetPrefix } from "../config";
-import { resolveOriginalPeerId } from "../peer-id-registry";
-import { getDingTalkRuntime } from "../runtime";
+import { getConfig, stripTargetPrefix } from "../platform/config";
+import { getDingTalkRuntime } from "../platform/runtime";
+import { resolveOriginalPeerId } from "./peer-id-registry";
 import { listKnownGroupTargets, listKnownUserTargets } from "./target-directory-store";
 
 export type DirectoryListParams = {

package/src/targeting/target-directory-store.ts

@@ -1,4 +1,4 @@
-import { readNamespaceJson, writeNamespaceJsonAtomic } from "../persistence-store";
+import { readNamespaceJson, writeNamespaceJsonAtomic } from "../shared/persistence-store";
 
 const TARGET_DIRECTORY_NAMESPACE = "targets.directory";
 const MAX_HISTORICAL_NAMES = 20;

package/src/targeting/target-input.ts

@@ -1,4 +1,4 @@
-import { stripTargetPrefix } from "../config";
+import { stripTargetPrefix } from "../platform/config";
 
 function stripProviderPrefix(raw: string): string {
   return raw.replace(/^(dingtalk|dd|ding)\s*:\s*/i, "");

package/dist/src/ack-reaction/dynamic-ack-reaction-events.d.ts

@@ -1,35 +0,0 @@
-export type DynamicAckReactionLogger = {
-    debug?: (msg: string) => void;
-    info?: (msg: string) => void;
-    warn?: (msg: string) => void;
-};
-export type RuntimeAgentEvent = {
-    stream?: string;
-    runId?: string;
-    sessionKey?: string;
-    data?: {
-        phase?: string;
-        name?: string;
-        args?: unknown;
-        runId?: string;
-        sessionKey?: string;
-        toolCallId?: string;
-        meta?: {
-            runId?: string;
-            sessionKey?: string;
-        } | null;
-    };
-};
-export type RuntimeEventsSurface = {
-    onAgentEvent?: (listener: (event: unknown) => void) => (() => void);
-};
-export declare function getEventRunId(event: RuntimeAgentEvent | undefined): string | undefined;
-export declare function getEventSessionKey(event: RuntimeAgentEvent | undefined): string | undefined;
-export declare function describeEvent(event: RuntimeAgentEvent | undefined): string;
-export declare function createDynamicAckReactionCorrelator(params: {
-    sessionKey: string;
-    enabled: boolean;
-    createdAt: number;
-    optimisticCaptureWindowMs: number;
-    log?: DynamicAckReactionLogger;
-}): (event: RuntimeAgentEvent | undefined) => boolean;

package/dist/src/config.d.ts

@@ -1,59 +0,0 @@
-import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
-import type { DingTalkConfig } from "./types";
-export { resolveRelativePath, resolveUserPath } from "./path-utils";
-export type RuntimeDingTalkConfig = Omit<DingTalkConfig, "clientSecret"> & {
-    clientSecret: string;
-};
-/**
- * Merge channel-level defaults into an account-specific config.
- * Account-level values take precedence; `accounts` key is excluded to avoid recursion.
- */
-export declare function mergeAccountWithDefaults(channelCfg: DingTalkConfig, accountCfg: DingTalkConfig): DingTalkConfig;
-/**
- * Resolve DingTalk config for an account.
- * Named accounts inherit channel-level defaults with account-level overrides.
- * Falls back to top-level config for single-account setups.
- */
-export declare function getConfig(cfg: OpenClawConfig, accountId?: string): DingTalkConfig;
-export declare function isConfigured(cfg: OpenClawConfig, accountId?: string): boolean;
-export declare function resolveRuntimeConfig(config: DingTalkConfig, log?: {
-    warn?: (message: string, data?: unknown) => void;
-}): Promise<RuntimeDingTalkConfig>;
-/**
- * Resolve the robot code used by DingTalk APIs.
- * DingTalk robotCode is always equal to clientId; this helper trims whitespace.
- */
-export declare function resolveRobotCode(config: Pick<DingTalkConfig, "clientId">): string;
-export declare function resolveGroupConfig(cfg: DingTalkConfig, groupId: string): {
-    systemPrompt?: string;
-    requireMention?: boolean;
-    groupAllowFrom?: string[];
-} | undefined;
-export declare function resolveAckReactionSetting(params: {
-    cfg: OpenClawConfig;
-    accountId?: string | null;
-    agentId?: string | null;
-}): string | undefined;
-/**
- * Strip group/user prefixes used by CLI targeting.
- * Returns raw DingTalk target ID and whether caller explicitly requested a user target.
- */
-export declare function stripTargetPrefix(target: string): {
-    targetId: string;
-    isExplicitUser: boolean;
-};
-/**
- * List all DingTalk account IDs from config
- */
-export declare function listDingTalkAccountIds(cfg: OpenClawConfig): string[];
-/**
- * Resolved DingTalk account with configuration status
- */
-export interface ResolvedDingTalkAccount extends DingTalkConfig {
-    accountId: string;
-    configured: boolean;
-}
-/**
- * Resolve a specific DingTalk account configuration
- */
-export declare function resolveDingTalkAccount(cfg: OpenClawConfig, accountId?: string | null): ResolvedDingTalkAccount;

package/src/ack-reaction/dynamic-ack-reaction-events.ts

@@ -1,123 +0,0 @@
-import { getErrorMessage } from "../utils";
-
-export type DynamicAckReactionLogger = {
-  debug?: (msg: string) => void;
-  info?: (msg: string) => void;
-  warn?: (msg: string) => void;
-};
-
-export type RuntimeAgentEvent = {
-  stream?: string;
-  runId?: string;
-  sessionKey?: string;
-  data?: {
-    phase?: string;
-    name?: string;
-    args?: unknown;
-    runId?: string;
-    sessionKey?: string;
-    toolCallId?: string;
-    meta?: {
-      runId?: string;
-      sessionKey?: string;
-    } | null;
-  };
-};
-
-export type RuntimeEventsSurface = {
-  onAgentEvent?: (listener: (event: unknown) => void) => (() => void);
-};
-
-function firstTrimmedString(...values: unknown[]): string | undefined {
-  for (const value of values) {
-    if (typeof value === "string" && value.trim()) {
-      return value.trim();
-    }
-  }
-  return undefined;
-}
-
-export function getEventRunId(event: RuntimeAgentEvent | undefined): string | undefined {
-  return firstTrimmedString(event?.runId, event?.data?.runId, event?.data?.meta?.runId);
-}
-
-export function getEventSessionKey(event: RuntimeAgentEvent | undefined): string | undefined {
-  return firstTrimmedString(event?.sessionKey, event?.data?.sessionKey, event?.data?.meta?.sessionKey);
-}
-
-export function describeEvent(event: RuntimeAgentEvent | undefined): string {
-  const stream = firstTrimmedString(event?.stream) || "-";
-  const phase = firstTrimmedString(event?.data?.phase) || "-";
-  const toolName = firstTrimmedString(event?.data?.name) || "-";
-  const toolCallId = firstTrimmedString(event?.data?.toolCallId) || "-";
-  return `stream=${stream} phase=${phase} runId=${getEventRunId(event) || "-"} ` +
-    `sessionKey=${getEventSessionKey(event) || "-"} toolCallId=${toolCallId} toolName=${toolName}`;
-}
-
-export function createDynamicAckReactionCorrelator(params: {
-  sessionKey: string;
-  enabled: boolean;
-  createdAt: number;
-  optimisticCaptureWindowMs: number;
-  log?: DynamicAckReactionLogger;
-}) {
-  let activeRunId: string | undefined;
-  let correlationUnavailableLogged = false;
-  let optimisticCaptureCount = 0;
-
-  return (event: RuntimeAgentEvent | undefined): boolean => {
-    const eventRunId = getEventRunId(event);
-    const eventSessionKey = getEventSessionKey(event);
-    const eventStream = firstTrimmedString(event?.stream) || "";
-    const eventPhase = firstTrimmedString(event?.data?.phase) || "";
-
-    if (activeRunId) {
-      const matched = eventRunId === activeRunId;
-      params.log?.debug?.(
-        `[DingTalk] Dynamic reaction correlation by runId matched=${matched} activeRunId=${activeRunId} ` +
-        `eventRunId=${eventRunId || "-"} eventSessionKey=${eventSessionKey || "-"}`,
-      );
-      return matched;
-    }
-
-    if (eventSessionKey === params.sessionKey) {
-      if (eventRunId) {
-        activeRunId = eventRunId;
-        params.log?.debug?.(
-          `[DingTalk] Dynamic reaction captured active runId=${activeRunId} from sessionKey=${params.sessionKey}`,
-        );
-      } else {
-        params.log?.debug?.(
-          `[DingTalk] Dynamic reaction correlated by sessionKey=${params.sessionKey} without runId`,
-        );
-      }
-      return true;
-    }
-
-    if (
-      optimisticCaptureCount === 0
-      && eventStream === "lifecycle"
-      && eventPhase === "start"
-      && eventRunId
-      && !eventSessionKey
-      && Date.now() - params.createdAt <= params.optimisticCaptureWindowMs
-    ) {
-      optimisticCaptureCount += 1;
-      activeRunId = eventRunId;
-      params.log?.debug?.(
-        `[DingTalk] Dynamic reaction optimistically captured active runId=${activeRunId} ` +
-        `from first lifecycle event without sessionKey windowMs=${params.optimisticCaptureWindowMs}`,
-      );
-      return true;
-    }
-
-    if (!correlationUnavailableLogged && params.enabled) {
-      correlationUnavailableLogged = true;
-      params.log?.debug?.(
-        `[DingTalk] Dynamic reaction ignored uncorrelated agent events; ` +
-        `reason=${getErrorMessage(eventRunId || eventSessionKey || "waiting for sessionKey/runId match")}`,
-      );
-    }
-    return false;
-  };
-}