Merge c6c170b into 968aa51

MonkeyLeeT · web-flow · commit f63b826e4fb7 · 2026-07-02T23:04:34.000+02:00
diff --git a/docs/plugins/sdk-channel-plugins.md b/docs/plugins/sdk-channel-plugins.md
@@ -149,13 +149,14 @@ Most channel plugins do not need approval-specific code.
 - `ChannelPlugin.approvals` is removed. Put approval delivery/native/render/auth facts on `approvalCapability`.
 - `plugin.auth` is login/logout only; core no longer reads approval auth hooks from that object.
 - `approvalCapability.authorizeActorAction` and `approvalCapability.getActionAvailabilityState` are the canonical approval-auth seam.
-- Use `approvalCapability.getActionAvailabilityState` for same-chat approval auth availability.
+- Use `approvalCapability.getActionAvailabilityState` for same-chat approval auth availability. Keep configured approvers available for `/approve` even when native delivery is disabled; use native initiating-surface state for delivery/setup guidance instead.
 - If your channel exposes native exec approvals, use `approvalCapability.getExecInitiatingSurfaceState` for the initiating-surface/native-client state when it differs from same-chat approval auth. Core uses that exec-specific hook to distinguish `enabled` vs `disabled`, decide whether the initiating channel supports native exec approvals, and include the channel in native-client fallback guidance. `createApproverRestrictedNativeApprovalCapability(...)` fills this in for the common case.
 - Use `outbound.shouldSuppressLocalPayloadPrompt` or `outbound.beforeDeliverPayload` for channel-specific payload lifecycle behavior such as hiding duplicate local approval prompts or sending typing indicators before delivery.
 - Use `approvalCapability.delivery` only for native approval routing or fallback suppression.
 - Use `approvalCapability.nativeRuntime` for channel-owned native approval facts. Keep it lazy on hot channel entrypoints with `createLazyChannelApprovalNativeRuntimeAdapter(...)`, which can import your runtime module on demand while still letting core assemble the approval lifecycle.
 - Use `approvalCapability.render` only when a channel truly needs custom approval payloads instead of the shared renderer.
 - Use `approvalCapability.describeExecApprovalSetup` when the channel wants the disabled-path reply to explain the exact config knobs needed to enable native exec approvals. The hook receives `{ channel, channelLabel, accountId }`; named-account channels should render account-scoped paths such as `channels.<channel>.accounts.<id>.execApprovals.*` instead of top-level defaults.
+- Use `approvalCapability.describePluginApprovalSetup` when plugin approval failure guidance is safe to show for plugin approval no-route and timeout failures. `createApproverRestrictedNativeApprovalCapability(...)` does not infer this from `describeExecApprovalSetup`; pass the same helper explicitly only when plugin and exec approvals truly use the same native setup.
 - If a channel can infer stable owner-like DM identities from existing config, use `createResolvedApproverActionAuthAdapter` from `openclaw/plugin-sdk/approval-runtime` to restrict same-chat `/approve` without adding approval-specific core logic.
 - If custom approval auth intentionally allows only same-chat fallback, return `markImplicitSameChatApprovalAuthorization({ authorized: true })` from `openclaw/plugin-sdk/approval-auth-runtime`; otherwise core treats the result as explicit approver authorization.
 - If a channel-owned native callback resolves approvals directly, use `isImplicitSameChatApprovalAuthorization(...)` before resolving so implicit fallback still goes through the channel's normal actor authorization.
diff --git a/extensions/slack/src/approval-native.test.ts b/extensions/slack/src/approval-native.test.ts
@@ -162,6 +162,16 @@ describe("slack native approval adapter", () => {
     expect(text).not.toContain("`channels.slack.execApprovals.approvers`");
   });
 
+  it("does not reuse exec setup copy for plugin approval setup", () => {
+    expect(
+      slackApprovalCapability.describeExecApprovalSetup?.({
+        channel: "slack",
+        channelLabel: "Slack",
+      }),
+    ).toContain("`channels.slack.execApprovals.approvers`");
+    expect(slackApprovalCapability.describePluginApprovalSetup).toBeUndefined();
+  });
+
   it("resolves origin targets from slack turn source", async () => {
     const target = await resolveExecOriginTarget();
 
diff --git a/extensions/telegram/src/approval-native.ts b/extensions/telegram/src/approval-native.ts
@@ -82,16 +82,19 @@ const resolveTelegramApproverDmTargets = createChannelApproverDmTargetResolver({
   mapApprover: (approver) => ({ to: approver }),
 });
 
+function describeTelegramExecApprovalSetup({ accountId }: { accountId?: string | null }) {
+  const prefix =
+    accountId && accountId !== "default"
+      ? `channels.telegram.accounts.${accountId}`
+      : "channels.telegram";
+  return `Approve it from the Web UI or terminal UI for now. Telegram supports native exec approvals for this account. Configure \`${prefix}.execApprovals.approvers\` or \`commands.ownerAllowFrom\`; leave \`${prefix}.execApprovals.enabled\` unset/\`auto\` or set it to \`true\`.`;
+}
+
 const telegramNativeApprovalCapability = createApproverRestrictedNativeApprovalCapability({
   channel: "telegram",
   channelLabel: "Telegram",
-  describeExecApprovalSetup: ({ accountId }: { accountId?: string | null }) => {
-    const prefix =
-      accountId && accountId !== "default"
-        ? `channels.telegram.accounts.${accountId}`
-        : "channels.telegram";
-    return `Approve it from the Web UI or terminal UI for now. Telegram supports native exec approvals for this account. Configure \`${prefix}.execApprovals.approvers\` or \`commands.ownerAllowFrom\`; leave \`${prefix}.execApprovals.enabled\` unset/\`auto\` or set it to \`true\`.`;
-  },
+  describeExecApprovalSetup: describeTelegramExecApprovalSetup,
+  describePluginApprovalSetup: describeTelegramExecApprovalSetup,
   listAccountIds: listTelegramAccountIds,
   hasApprovers: ({ cfg, accountId }) =>
     getTelegramExecApprovalApprovers({ cfg, accountId }).length > 0,
diff --git a/src/agents/agent-tools.before-tool-call.e2e.test.ts b/src/agents/agent-tools.before-tool-call.e2e.test.ts
@@ -23,6 +23,7 @@ import { createEmptyPluginRegistry } from "../plugins/registry-empty.js";
 import { setActivePluginRegistry } from "../plugins/runtime.js";
 import { setPluginToolMeta } from "../plugins/tools.js";
 import { createCanonicalFixtureSkill } from "../skills/test-support/test-helpers.js";
+import { createChannelTestPluginBase, createTestRegistry } from "../test-utils/channel-plugins.js";
 import {
   getBeforeToolCallPolicyDiagnosticState,
   runBeforeToolCallHook,
@@ -1042,6 +1043,26 @@ describe("before_tool_call requireApproval handling", () => {
     }
   }
 
+  function registerTelegramPluginApprovalSetup(): void {
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "telegram",
+          source: "test",
+          plugin: {
+            ...createChannelTestPluginBase({ id: "telegram", label: "Telegram" }),
+            approvalCapability: {
+              native: {},
+              getActionAvailabilityState: () => ({ kind: "enabled" as const }),
+              getExecInitiatingSurfaceState: () => ({ kind: "disabled" as const }),
+              describePluginApprovalSetup: () => "Configure Telegram native approval setup.",
+            },
+          },
+        },
+      ]),
+    );
+  }
+
   beforeEach(() => {
     resetDiagnosticSessionStateForTest();
     resetDiagnosticEventsForTest();
@@ -1492,25 +1513,39 @@ describe("before_tool_call requireApproval handling", () => {
     expect(result).toHaveProperty("reason", "Denied by user");
   });
 
-  it("blocks on timeout with default deny behavior", async () => {
+  it("blocks turn-source plugin approval timeouts with setup guidance", async () => {
+    registerTelegramPluginApprovalSetup();
     hookRunner.runBeforeToolCall.mockResolvedValue({
       requireApproval: {
         title: "Timeout test",
         description: "Will time out",
       },
     });
 
-    mockCallGateway.mockResolvedValueOnce({ id: "server-id-3", status: "accepted" });
+    mockCallGateway.mockResolvedValueOnce({
+      id: "server-id-3",
+      status: "accepted",
+      deliveryRoute: "turn-source",
+    });
     mockCallGateway.mockResolvedValueOnce({ id: "server-id-3", decision: null });
 
     const result = await runBeforeToolCallHook({
       toolName: "bash",
       params: {},
-      ctx: { agentId: "main", sessionKey: "main" },
+      ctx: {
+        agentId: "main",
+        sessionKey: "main",
+        turnSourceChannel: "telegram",
+        turnSourceTo: "-100123456789",
+        turnSourceAccountId: "default",
+      },
     });
 
     expect(result.blocked).toBe(true);
-    expect(result).toHaveProperty("reason", "Approval timed out");
+    expect(result).toHaveProperty(
+      "reason",
+      "Approval timed out\n\nConfigure Telegram native approval setup.",
+    );
   });
 
   it("allows on timeout when timeoutBehavior is allow and preserves hook params", async () => {
diff --git a/src/agents/agent-tools.before-tool-call.ts b/src/agents/agent-tools.before-tool-call.ts
@@ -30,6 +30,10 @@ import {
   freezeDiagnosticTraceContext,
   type DiagnosticTraceContext,
 } from "../infra/diagnostic-trace-context.js";
+import {
+  describeNativePluginApprovalClientSetup,
+  resolveApprovalInitiatingSurfaceState,
+} from "../infra/exec-approval-surface.js";
 import {
   DEFAULT_PLUGIN_APPROVAL_TIMEOUT_MS,
   MAX_PLUGIN_APPROVAL_TIMEOUT_MS,
@@ -643,6 +647,43 @@ function notifyPluginApprovalResolution(
   }
 }
 
+function buildPluginApprovalFailureReason(params: {
+  fallbackReason: string;
+  ctx?: HookContext;
+}): string {
+  const turnSourceChannel = params.ctx?.turnSourceChannel;
+  if (!turnSourceChannel?.trim()) {
+    return params.fallbackReason;
+  }
+  const nativePluginSurface = resolveApprovalInitiatingSurfaceState({
+    channel: turnSourceChannel,
+    accountId: params.ctx?.turnSourceAccountId,
+    cfg: params.ctx?.config,
+    approvalKind: "plugin",
+  });
+  const setupText = describeNativePluginApprovalClientSetup({
+    channel: nativePluginSurface.channel,
+    channelLabel: nativePluginSurface.channelLabel,
+    accountId: nativePluginSurface.accountId,
+  });
+  if (!setupText) {
+    return params.fallbackReason;
+  }
+  const nativeDeliverySurface =
+    nativePluginSurface.kind === "disabled"
+      ? nativePluginSurface
+      : resolveApprovalInitiatingSurfaceState({
+          channel: turnSourceChannel,
+          accountId: params.ctx?.turnSourceAccountId,
+          cfg: params.ctx?.config,
+          approvalKind: "exec",
+        });
+  if (nativeDeliverySurface.kind !== "disabled") {
+    return params.fallbackReason;
+  }
+  return `${params.fallbackReason}\n\n${setupText}`;
+}
+
 async function requestPluginToolApproval(params: {
   approval: PluginApprovalRequest;
   toolName: string;
@@ -660,6 +701,7 @@ async function requestPluginToolApproval(params: {
       id?: string;
       status?: string;
       decision?: string | null;
+      deliveryRoute?: string;
     } = await callGatewayTool(
       "plugin.approval.request",
       // Buffer beyond the approval timeout so the gateway can clean up
@@ -705,7 +747,10 @@ async function requestPluginToolApproval(params: {
           blocked: true,
           kind: "failure",
           deniedReason: "plugin-approval",
-          reason: "Plugin approval unavailable (no approval route)",
+          reason: buildPluginApprovalFailureReason({
+            fallbackReason: "Plugin approval unavailable (no approval route)",
+            ctx: params.ctx,
+          }),
           params: params.baseParams,
         };
       }
@@ -779,11 +824,18 @@ async function requestPluginToolApproval(params: {
         approvalResolution: resolution,
       };
     }
+    const timeoutReason =
+      requestResult?.deliveryRoute === "turn-source"
+        ? buildPluginApprovalFailureReason({
+            fallbackReason: "Approval timed out",
+            ctx: params.ctx,
+          })
+        : "Approval timed out";
     return {
       blocked: true,
       kind: "failure",
       deniedReason: "plugin-approval",
-      reason: "Approval timed out",
+      reason: timeoutReason,
       params: params.baseParams,
     };
   } catch (err) {
diff --git a/src/auto-reply/reply/commands-approve.test.ts b/src/auto-reply/reply/commands-approve.test.ts
@@ -441,7 +441,7 @@ describe("handleApproveCommand", () => {
 
   function createTelegramApproveCfg(
     execApprovals: {
-      enabled: true;
+      enabled: boolean;
       approvers: string[];
       target: "dm";
     } | null = { enabled: true, approvers: ["123"], target: "dm" },
@@ -544,6 +544,28 @@ describe("handleApproveCommand", () => {
     expectApprovalResolverCall({ method: "exec.approval.resolve", id: "abc12345" });
   });
 
+  it("accepts forwarded Telegram plugin approvals from approvers when native delivery is disabled", async () => {
+    const params = buildApproveParams(
+      "/approve plugin:abc12345 allow-once",
+      createTelegramApproveCfg({ enabled: false, approvers: ["123"], target: "dm" }),
+      {
+        Provider: "telegram",
+        Surface: "telegram",
+        SenderId: "123",
+      },
+    );
+    params.command.isAuthorizedSender = false;
+    resolveApprovalOverGatewayMock.mockResolvedValue(undefined);
+
+    const result = await handleApproveCommand(params, true);
+    expect(result?.shouldContinue).toBe(false);
+    expect(result?.reply?.text).toContain("Approval allow-once submitted");
+    expectApprovalResolverCall({
+      method: "plugin.approval.resolve",
+      id: "plugin:abc12345",
+    });
+  });
+
   it("honors the configured default account for omitted-account /approve auth", async () => {
     setActivePluginRegistry(
       createTestRegistry([
diff --git a/src/channels/plugins/approvals.test.ts b/src/channels/plugins/approvals.test.ts
@@ -56,18 +56,21 @@ describe("resolveChannelApprovalAdapter", () => {
     const delivery = { hasConfiguredDmRoute: vi.fn() };
     const nativeRuntime = createNativeRuntimeStub();
     const describeExecApprovalSetup = vi.fn();
+    const describePluginApprovalSetup = vi.fn();
 
     expect(
       resolveChannelApprovalAdapter({
         approvalCapability: {
           describeExecApprovalSetup,
+          describePluginApprovalSetup,
           delivery,
           nativeRuntime,
           authorizeActorAction: vi.fn(),
         },
       }),
     ).toEqual({
       describeExecApprovalSetup,
+      describePluginApprovalSetup,
       delivery,
       nativeRuntime,
       render: undefined,
diff --git a/src/channels/plugins/approvals.ts b/src/channels/plugins/approvals.ts
@@ -36,6 +36,7 @@ export function resolveChannelApprovalAdapter(
   }
   return {
     describeExecApprovalSetup: capability.describeExecApprovalSetup,
+    describePluginApprovalSetup: capability.describePluginApprovalSetup,
     delivery: capability.delivery,
     nativeRuntime: capability.nativeRuntime,
     render: capability.render,
diff --git a/src/channels/plugins/types.adapters.ts b/src/channels/plugins/types.adapters.ts
@@ -636,6 +636,11 @@ export type ChannelApprovalAdapter = {
     channelLabel: string;
     accountId?: string;
   }) => string | null | undefined;
+  describePluginApprovalSetup?: (params: {
+    channel: string;
+    channelLabel: string;
+    accountId?: string;
+  }) => string | null | undefined;
 };
 
 export type ChannelApprovalCapability = ChannelApprovalAdapter & {
diff --git a/src/gateway/server-methods/approval-shared.test.ts b/src/gateway/server-methods/approval-shared.test.ts
@@ -299,7 +299,7 @@ describe("handlePendingApprovalRequest", () => {
     ).toBe(false);
   });
 
-  it("does not resolve turn-source routes when approval clients are already available", async () => {
+  it("reports an active approval client instead of the manual turn-source route", async () => {
     const manager = new ExecApprovalManager();
     const record = manager.create(
       {
@@ -334,6 +334,15 @@ describe("handlePendingApprovalRequest", () => {
 
     await Promise.resolve();
     expect(hasApprovalTurnSourceRouteMock).not.toHaveBeenCalled();
+    expect(respond).toHaveBeenCalledWith(
+      true,
+      expect.objectContaining({
+        id: "approval-with-client",
+        status: "accepted",
+        deliveryRoute: "approval-client",
+      }),
+      undefined,
+    );
 
     expect(manager.resolve(record.id, "allow-once")).toBe(true);
     await requestPromise;
diff --git a/src/gateway/server-methods/approval-shared.ts b/src/gateway/server-methods/approval-shared.ts
@@ -58,6 +58,8 @@ type PendingApprovalListEntry<TPayload> = {
   expiresAtMs: number;
 };
 
+type ApprovalRequestDeliveryRoute = "approval-client" | "forwarder" | "turn-source" | "none";
+
 type ApprovalResolveParams = {
   id: string;
   decision: string;
@@ -473,6 +475,13 @@ export async function handlePendingApprovalRequest<
       turnSourceAccountId: params.record.request.turnSourceAccountId,
       approvalKind: params.approvalKind ?? "exec",
     });
+  const deliveryRoute: ApprovalRequestDeliveryRoute = delivered
+    ? "forwarder"
+    : hasApprovalClients
+      ? "approval-client"
+      : hasTurnSourceRoute
+        ? "turn-source"
+        : "none";
 
   if (
     params.requireDeliveryRoute !== false &&
@@ -501,6 +510,9 @@ export async function handlePendingApprovalRequest<
       {
         status: "accepted",
         id: params.record.id,
+        // Agent-side timeouts use this to distinguish delivered prompts from
+        // requests kept pending only because manual /approve routing may work.
+        deliveryRoute,
         createdAtMs: params.record.createdAtMs,
         expiresAtMs: params.record.expiresAtMs,
       },
diff --git a/src/gateway/server-methods/plugin-approval.test.ts b/src/gateway/server-methods/plugin-approval.test.ts
@@ -374,6 +374,7 @@ describe("createPluginApprovalHandlers", () => {
 
         const requestPromise = handlers["plugin.approval.request"](opts);
         const approvalId = await waitForAcceptedApproval(respond);
+        expect(acceptedResult(respond).deliveryRoute).toBe("turn-source");
         manager.resolve(approvalId, "allow-once");
 
         await requestPromise;
diff --git a/src/infra/exec-approval-surface.ts b/src/infra/exec-approval-surface.ts
diff --git a/src/plugin-sdk/approval-delivery-helpers.test.ts b/src/plugin-sdk/approval-delivery-helpers.test.ts
diff --git a/src/plugin-sdk/approval-delivery-helpers.ts b/src/plugin-sdk/approval-delivery-helpers.ts

Original file line number	Diff line number	Diff line change
`@@ -36,6 +36,7 @@ export function resolveChannelApprovalAdapter(`
`36`	`36`	`}`
`37`	`37`	`return {`
`38`	`38`	`describeExecApprovalSetup: capability.describeExecApprovalSetup,`
	`39`	`+ describePluginApprovalSetup: capability.describePluginApprovalSetup,`
`39`	`40`	`delivery: capability.delivery,`
`40`	`41`	`nativeRuntime: capability.nativeRuntime,`
`41`	`42`	`render: capability.render,`