fix: scope native approval fallback suppression

cyphercodes · cyphercodes · commit 89f520eb70e8 · 2026-06-19T13:34:35.000+03:00
diff --git a/extensions/telegram/src/approval-native.ts b/extensions/telegram/src/approval-native.ts
@@ -106,6 +106,7 @@ const telegramNativeApprovalCapability = createApproverRestrictedNativeApprovalC
   resolveNativeDeliveryMode: ({ cfg, accountId }) =>
     resolveTelegramExecApprovalTarget({ cfg, accountId }),
   requireMatchingTurnSourceChannel: true,
+  allowMissingTurnSourceChannelForSuppression: true,
   resolveSuppressionAccountId: ({ target, request }) =>
     normalizeOptionalString(target.accountId) ??
     normalizeOptionalString(request.request.turnSourceAccountId),
diff --git a/src/plugin-sdk/approval-delivery-helpers.test.ts b/src/plugin-sdk/approval-delivery-helpers.test.ts
@@ -175,6 +175,7 @@ describe("createApproverRestrictedNativeApprovalAdapter", () => {
       isNativeDeliveryEnabled,
       resolveNativeDeliveryMode: () => "both",
       requireMatchingTurnSourceChannel: true,
+      allowMissingTurnSourceChannelForSuppression: true,
       resolveSuppressionAccountId: ({ request }) =>
         request.request.turnSourceAccountId?.trim() || undefined,
     });
@@ -263,6 +264,38 @@ describe("createApproverRestrictedNativeApprovalAdapter", () => {
       }),
     ).toBe(true);
   });
+
+  it("keeps forwarding fallback for missing-source channels unless explicitly opted in", () => {
+    const adapter = createApproverRestrictedNativeApprovalAdapter({
+      channel: "matrix",
+      channelLabel: "Matrix",
+      listAccountIds: () => [],
+      hasApprovers: () => true,
+      isExecAuthorizedSender: () => true,
+      isNativeDeliveryEnabled: () => true,
+      resolveNativeDeliveryMode: () => "both",
+      requireMatchingTurnSourceChannel: true,
+    });
+    const shouldSuppressForwardingFallback = adapter.delivery?.shouldSuppressForwardingFallback;
+    if (!shouldSuppressForwardingFallback) {
+      throw new Error("delivery suppression helper unavailable");
+    }
+
+    expect(
+      shouldSuppressForwardingFallback({
+        cfg: {} as never,
+        approvalKind: "exec",
+        target: { channel: "matrix", to: "target-1" },
+        request: {
+          request: {
+            command: "pwd",
+            turnSourceChannel: null,
+            turnSourceAccountId: "room-1",
+          },
+        } as never,
+      }),
+    ).toBe(false);
+  });
 });
 
 describe("createApproverRestrictedNativeApprovalCapability", () => {
diff --git a/src/plugin-sdk/approval-delivery-helpers.ts b/src/plugin-sdk/approval-delivery-helpers.ts
@@ -1,3 +1,4 @@
+// Approval delivery helpers format approval prompts and results for channel plugins.
 import type { ExecApprovalRequest } from "../infra/exec-approvals.js";
 import type { PluginApprovalRequest } from "../infra/plugin-approvals.js";
 import type { ChannelApprovalCapability } from "./channel-contract.js";
@@ -15,49 +16,74 @@ type ChannelApprovalCapabilitySurfaces = Pick<
 >;
 
 type ApprovalAdapterParams = {
+  /** Full config used to inspect channel approval settings. */
   cfg: OpenClawConfig;
+  /** Optional channel account id for account-scoped approval settings. */
   accountId?: string | null;
+  /** Actor attempting the approval action. */
   senderId?: string | null;
 };
 
 type DeliverySuppressionParams = {
+  /** Full config used to inspect native approval delivery settings. */
   cfg: OpenClawConfig;
+  /** Approval kind being delivered. */
   approvalKind: ApprovalKind;
+  /** Forwarding fallback target under consideration. */
   target: { channel: string; accountId?: string | null };
+  /** Approval request metadata, including original turn source when available. */
   request: { request: { turnSourceChannel?: string | null; turnSourceAccountId?: string | null } };
 };
 
 type ApproverRestrictedNativeApprovalParams = {
+  /** Channel id that owns this native approval capability. */
   channel: string;
+  /** Human-readable channel label used in denial messages. */
   channelLabel: string;
+  /** Lists configured account ids so DM-route availability can scan every account. */
   listAccountIds: (cfg: OpenClawConfig) => string[];
+  /** Whether an account has approvers configured. */
   hasApprovers: (params: ApprovalAdapterParams) => boolean;
+  /** Whether a sender can approve exec approvals for this account. */
   isExecAuthorizedSender: (params: ApprovalAdapterParams) => boolean;
+  /** Optional plugin approval authorization hook; defaults to exec authorization. */
   isPluginAuthorizedSender?: (params: ApprovalAdapterParams) => boolean;
+  /** Whether native approval delivery is enabled for an account. */
   isNativeDeliveryEnabled: (params: { cfg: OpenClawConfig; accountId?: string | null }) => boolean;
+  /** Native delivery target preference for an account. */
   resolveNativeDeliveryMode: (params: {
     cfg: OpenClawConfig;
     accountId?: string | null;
   }) => NativeApprovalDeliveryMode;
+  /** Requires the approval request's original turn channel to match this channel before suppression. */
   requireMatchingTurnSourceChannel?: boolean;
+  /** Allows suppression when the original turn source is unavailable but the native route can still handle it. */
+  allowMissingTurnSourceChannelForSuppression?: boolean;
+  /** Optional account id resolver used when deciding forwarding-fallback suppression. */
   resolveSuppressionAccountId?: (params: DeliverySuppressionParams) => string | undefined;
+  /** Resolves the original channel target for native approval delivery. */
   resolveOriginTarget?: (params: {
     cfg: OpenClawConfig;
     accountId?: string | null;
     approvalKind: ApprovalKind;
     request: NativeApprovalRequest;
   }) => NativeApprovalTarget | null | Promise<NativeApprovalTarget | null>;
+  /** Resolves approver DM targets for native approval delivery. */
   resolveApproverDmTargets?: (params: {
     cfg: OpenClawConfig;
     accountId?: string | null;
     approvalKind: ApprovalKind;
     request: NativeApprovalRequest;
   }) => NativeApprovalTarget[] | Promise<NativeApprovalTarget[]>;
+  /** Whether DM-only native delivery should also notify the origin channel. */
   notifyOriginWhenDmOnly?: boolean;
+  /** Native runtime hooks used by channel-specific delivery implementations. */
   nativeRuntime?: ChannelApprovalCapability["nativeRuntime"];
+  /** Optional setup description helper shown when exec approvals are unavailable. */
   describeExecApprovalSetup?: ChannelApprovalCapability["describeExecApprovalSetup"];
 };
 
+/** Build the canonical approval capability for channels that restrict approvals to configured approvers. */
 function buildApproverRestrictedNativeApprovalCapability(
   params: ApproverRestrictedNativeApprovalParams,
 ): ChannelApprovalCapability {
@@ -148,6 +174,9 @@ function buildApproverRestrictedNativeApprovalCapability(
           const turnSourceChannel = normalizeMessageChannel(
             input.request.request.turnSourceChannel,
           );
+          if (!turnSourceChannel && !params.allowMissingTurnSourceChannelForSuppression) {
+            return false;
+          }
           if (turnSourceChannel && turnSourceChannel !== params.channel) {
             return false;
           }
@@ -157,6 +186,8 @@ function buildApproverRestrictedNativeApprovalCapability(
           (resolvedAccountId === undefined
             ? input.target.accountId?.trim()
             : resolvedAccountId.trim()) || undefined;
+        // Suppress generic forwarding only when this channel's native route can
+        // handle the same account; otherwise the fallback is the only delivery path.
         return params.isNativeDeliveryEnabled({ cfg: input.cfg, accountId });
       },
     },
@@ -188,25 +219,38 @@ function buildApproverRestrictedNativeApprovalCapability(
   });
 }
 
+/** Build the legacy split approval adapter shape for approver-restricted native channels. */
 export function createApproverRestrictedNativeApprovalAdapter(
   params: ApproverRestrictedNativeApprovalParams,
 ) {
   return splitChannelApprovalCapability(buildApproverRestrictedNativeApprovalCapability(params));
 }
 
+/** Assemble a channel approval capability from its auth, delivery, render, and native surfaces. */
 export function createChannelApprovalCapability(params: {
+  /** Authorizes actors attempting approval actions. */
   authorizeActorAction?: ChannelApprovalCapability["authorizeActorAction"];
+  /** Reports whether approval actions are generally available. */
   getActionAvailabilityState?: ChannelApprovalCapability["getActionAvailabilityState"];
+  /** Reports whether exec approvals can start from the initiating surface. */
   getExecInitiatingSurfaceState?: ChannelApprovalCapability["getExecInitiatingSurfaceState"];
+  /** Optional command behavior override for approval replies. */
   resolveApproveCommandBehavior?: ChannelApprovalCapability["resolveApproveCommandBehavior"];
+  /** Optional setup copy for unavailable exec approval paths. */
   describeExecApprovalSetup?: ChannelApprovalCapability["describeExecApprovalSetup"];
+  /** Delivery fallback and DM-route helpers. */
   delivery?: ChannelApprovalCapability["delivery"];
+  /** Native runtime hooks for channel-specific approval delivery. */
   nativeRuntime?: ChannelApprovalCapability["nativeRuntime"];
+  /** Render hooks for pending/resolved approval payloads. */
   render?: ChannelApprovalCapability["render"];
+  /** Native target/capability discovery hooks. */
   native?: ChannelApprovalCapability["native"];
   /** @deprecated Pass delivery/nativeRuntime/render/native directly. */
   approvals?: Partial<ChannelApprovalCapabilitySurfaces>;
 }): ChannelApprovalCapability {
+  // Keep the approvals alias for shipped plugin-sdk callers; registry tests track
+  // this compatibility marker until the public deprecation window closes.
   const surfaces: ChannelApprovalCapabilitySurfaces = {
     delivery: params.delivery ?? params.approvals?.delivery,
     nativeRuntime: params.nativeRuntime ?? params.approvals?.nativeRuntime,
@@ -226,6 +270,7 @@ export function createChannelApprovalCapability(params: {
   };
 }
 
+/** Split the canonical approval capability into the adapter shape older channel loaders consume. */
 export function splitChannelApprovalCapability(capability: ChannelApprovalCapability): {
   auth: {
     authorizeActorAction?: ChannelApprovalCapability["authorizeActorAction"];
@@ -254,6 +299,7 @@ export function splitChannelApprovalCapability(capability: ChannelApprovalCapabi
   };
 }
 
+/** Build the canonical approval capability for approver-restricted native delivery channels. */
 export function createApproverRestrictedNativeApprovalCapability(
   params: ApproverRestrictedNativeApprovalParams,
 ): ChannelApprovalCapability {
