From 53872cf8e75562db012b66f888928524daff08d2 Mon Sep 17 00:00:00 2001
From: Gustavo Madeira Santana <gumadeiras@gmail.com>
Date: Thu, 26 Feb 2026 01:12:49 -0500
Subject: [PATCH] Onboarding: add hook precedence tests and docs

---
 docs/tools/plugin.md                  |  23 +++++
 src/commands/onboard-channels.test.ts | 124 ++++++++++++++++++++++++++
 2 files changed, 147 insertions(+)

diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md
index 9250501f2d9..3dc575088eb 100644
--- a/docs/tools/plugin.md
+++ b/docs/tools/plugin.md
@@ -452,6 +452,29 @@ Notes:
 - `meta.preferOver` lists channel ids to skip auto-enable when both are configured.
 - `meta.detailLabel` and `meta.systemImage` let UIs show richer channel labels/icons.
 
+### Channel onboarding hooks
+
+Channel plugins can define optional onboarding hooks on `plugin.onboarding`:
+
+- `configure(ctx)` is the baseline setup flow.
+- `configureInteractive(ctx)` can fully own interactive setup for both configured and unconfigured states.
+- `configureWhenConfigured(ctx)` can override behavior only for already configured channels.
+
+Hook precedence in the wizard:
+
+1. `configureInteractive` (if present)
+2. `configureWhenConfigured` (only when channel status is already configured)
+3. fallback to `configure`
+
+Context details:
+
+- `configureInteractive` and `configureWhenConfigured` receive:
+  - `configured` (`true` or `false`)
+  - `label` (user-facing channel name used by prompts)
+  - plus the shared config/runtime/prompter/options fields
+- Returning `"skip"` leaves selection and account tracking unchanged.
+- Returning `{ cfg, accountId? }` applies config updates and records account selection.
+
 ### Write a new messaging channel (step‑by‑step)
 
 Use this when you want a **new chat surface** (a "messaging channel"), not a model provider.
diff --git a/src/commands/onboard-channels.test.ts b/src/commands/onboard-channels.test.ts
index a6142faf843..cd146b82c09 100644
--- a/src/commands/onboard-channels.test.ts
+++ b/src/commands/onboard-channels.test.ts
@@ -431,4 +431,128 @@ describe("setupChannels", () => {
       restore();
     }
   });
+
+  it("respects configureWhenConfigured skip without mutating selection or account state", async () => {
+    const select = vi.fn(async ({ message }: { message: string }) => {
+      if (message === "Select channel (QuickStart)") {
+        return "telegram";
+      }
+      throw new Error(`unexpected select prompt: ${message}`);
+    });
+    const selection = vi.fn();
+    const onAccountId = vi.fn();
+    const configureWhenConfigured = vi.fn(async () => "skip" as const);
+    const configure = vi.fn(async () => {
+      throw new Error("configure should not run when configureWhenConfigured handles skip");
+    });
+    const restore = patchChannelOnboardingAdapter("telegram", {
+      getStatus: vi.fn(async ({ cfg }) => ({
+        channel: "telegram",
+        configured: Boolean(cfg.channels?.telegram?.botToken),
+        statusLines: [],
+      })),
+      configureInteractive: undefined,
+      configureWhenConfigured,
+      configure,
+    });
+    const { multiselect, text } = createUnexpectedPromptGuards();
+
+    const prompter = createPrompter({
+      select: select as unknown as WizardPrompter["select"],
+      multiselect,
+      text,
+    });
+
+    const runtime = createExitThrowingRuntime();
+    try {
+      const cfg = await setupChannels(
+        {
+          channels: {
+            telegram: {
+              botToken: "old-token",
+            },
+          },
+        } as OpenClawConfig,
+        runtime,
+        prompter,
+        {
+          skipConfirm: true,
+          quickstartDefaults: true,
+          onSelection: selection,
+          onAccountId,
+        },
+      );
+
+      expect(configureWhenConfigured).toHaveBeenCalledWith(
+        expect.objectContaining({ configured: true, label: expect.any(String) }),
+      );
+      expect(configure).not.toHaveBeenCalled();
+      expect(selection).toHaveBeenCalledWith([]);
+      expect(onAccountId).not.toHaveBeenCalled();
+      expect(cfg.channels?.telegram?.botToken).toBe("old-token");
+    } finally {
+      restore();
+    }
+  });
+
+  it("prefers configureInteractive over configureWhenConfigured when both hooks exist", async () => {
+    const select = vi.fn(async ({ message }: { message: string }) => {
+      if (message === "Select channel (QuickStart)") {
+        return "telegram";
+      }
+      throw new Error(`unexpected select prompt: ${message}`);
+    });
+    const selection = vi.fn();
+    const onAccountId = vi.fn();
+    const configureInteractive = vi.fn(async () => "skip" as const);
+    const configureWhenConfigured = vi.fn(async () => {
+      throw new Error("configureWhenConfigured should not run when configureInteractive exists");
+    });
+    const restore = patchChannelOnboardingAdapter("telegram", {
+      getStatus: vi.fn(async ({ cfg }) => ({
+        channel: "telegram",
+        configured: Boolean(cfg.channels?.telegram?.botToken),
+        statusLines: [],
+      })),
+      configureInteractive,
+      configureWhenConfigured,
+    });
+    const { multiselect, text } = createUnexpectedPromptGuards();
+
+    const prompter = createPrompter({
+      select: select as unknown as WizardPrompter["select"],
+      multiselect,
+      text,
+    });
+
+    const runtime = createExitThrowingRuntime();
+    try {
+      await setupChannels(
+        {
+          channels: {
+            telegram: {
+              botToken: "old-token",
+            },
+          },
+        } as OpenClawConfig,
+        runtime,
+        prompter,
+        {
+          skipConfirm: true,
+          quickstartDefaults: true,
+          onSelection: selection,
+          onAccountId,
+        },
+      );
+
+      expect(configureInteractive).toHaveBeenCalledWith(
+        expect.objectContaining({ configured: true, label: expect.any(String) }),
+      );
+      expect(configureWhenConfigured).not.toHaveBeenCalled();
+      expect(selection).toHaveBeenCalledWith([]);
+      expect(onAccountId).not.toHaveBeenCalled();
+    } finally {
+      restore();
+    }
+  });
 });