@masons/agent-network 0.4.26 → 0.5.1

package/dist/cli-setup.d.ts

@@ -1,39 +1,76 @@
 /**
- * CLI Setup Path — Device Code Flow via terminal prompts.
+ * CLI Login Path — OAuth 2.0 Device Authorization Grant (RFC 8628).
  *
- * Implements `configureInteractive()` hook for OpenClaw's
- * `openclaw channels login --channel agent-network` command.
+ * Implements `login()` hook for OpenClaw's 2026.4.x channel-plugin contract:
+ *     api.registerChannel({ plugin: { ..., auth: { login } } })
  *
- * Follows the WhatsApp channel pattern: CLI displays a code,
- * user authorizes in browser, credentials are returned to OpenClaw
- * which persists them to openclaw.json.
+ * Invoked by `openclaw channels login --channel agent-network`. CLI dispatch
+ * at `dist/channels-cli-Cc40S0aS.js:85` reads `plugin.auth?.login` and throws
+ * `"Channel ... does not support login"` if absent. See WhatsApp + Feishu
+ * bundled extensions for reference implementations of the same contract.
  *
+ * Flow:
+ *   1. POST {idpBaseUrl}/api/auth/device/code  with client_id + scope
+ *      → display user_code + verification_uri to the user
+ *   2. Poll {idpBaseUrl}/api/auth/device/token until access_token issued
+ *      → handles `expired_token`, `authorization_pending`, `slow_down`
+ *   3. POST {apiHost}/runtime/v1/onboard  with Bearer access_token
+ *      → list / select existing agent / create new (terminal prompter)
+ *   4. Persist credentials directly via `writeCredentials()` into
+ *      `openclaw.json`. (The CLI does NOT auto-persist after login returns —
+ *      unlike the legacy `configureInteractive` contract — so the plugin
+ *      owns the file write; see `runChannelLogin` in channels-cli source.)
+ *
+ * History. Pre-migration this file existed as a `setup_codes`-based bespoke
+ * flow (deleted in fd5568e8). A device-flow re-implementation landed in 0.5.0
+ * under `configureInteractive` mounted at `plugin.setup.configureInteractive`
+ * — but that mount path is not read by any known OpenClaw version (neither
+ * 2026.3.x's top-level `plugin.configureInteractive` nor 2026.4.x's
+ * `plugin.auth.login`). 0.5.1 corrects the mount point and adopts the
+ * 2026.4.x `{cfg, accountId, runtime, verbose, channelInput}` signature.
+ *
+ * See #1264 for the design rationale (single-driver Node semantic — re-running
+ * this flow rotates the api_key and evicts any previously-connected Runtime).
  */
-interface Prompter {
-    text(label: string, opts?: {
-        default?: string;
-    }): Promise<string>;
-    confirm(label: string): Promise<boolean>;
-    select(label: string, choices: string[]): Promise<string>;
-}
-interface ChannelSetupContext {
-    configured: boolean;
-    label: string;
-    cfg: Record<string, unknown>;
-    runtime: unknown;
-    prompter: Prompter;
-    options: Record<string, unknown>;
+/**
+ * Minimal OpenClaw runtime surface passed to `auth.login`. Exposed as
+ * `defaultRuntime` in `openclaw/dist/runtime-Dx7oeLYq.js` — plugins get
+ * only the output/exit channel, not a prompter (plugins build their own
+ * via @clack/prompts, which is what OpenClaw CLI uses internally too).
+ */
+interface OpenClawRuntime {
+    log(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    writeStdout(value: string): void;
+    writeJson(value: unknown, space?: number): void;
+    exit(code: number): void;
 }
-type SetupResult = "skip" | {
+/**
+ * Context passed by OpenClaw CLI to `plugin.auth.login`. Matches the call
+ * site at `dist/channels-cli-Cc40S0aS.js:89`:
+ *     await login({ cfg, accountId, runtime, verbose, channelInput });
+ */
+interface AuthLoginContext {
     cfg: Record<string, unknown>;
     accountId?: string;
-};
+    runtime: OpenClawRuntime;
+    verbose?: boolean;
+    channelInput?: string;
+}
 /**
- * Interactive Device Code Flow for OpenClaw CLI.
+ * Channel login hook — invoked by `openclaw channels login --channel agent-network`.
+ *
+ * Unlike the legacy `configureInteractive` contract (which returned a config
+ * object for the CLI to persist), the 2026.4.x `auth.login` contract returns
+ * void and expects the plugin to persist any config changes itself. We use
+ * `writeCredentials()` in config.ts, which writes `openclaw.json` atomically
+ * and bumps the state-cache generation so Layer B's dynamic context re-reads
+ * on the next turn.
  *
- * Called by `openclaw channels login --channel agent-network` or the onboarding wizard.
- * Returns `{ cfg, accountId }` — OpenClaw CLI handles writing to openclaw.json.
+ * Errors during device flow or onboarding are surfaced via `ctx.runtime.error`
+ * (not thrown) so OpenClaw CLI doesn't display a stack trace — matches the
+ * WhatsApp/Feishu pattern.
  */
-export declare function configureInteractive(ctx: ChannelSetupContext): Promise<SetupResult>;
+export declare function login(ctx: AuthLoginContext): Promise<void>;
 export {};
 //# sourceMappingURL=cli-setup.d.ts.map

package/dist/cli-setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-setup.d.ts","sourceRoot":"","sources":["../src/cli-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkBH,UAAU,QAAQ;IAChB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAED,UAAU,mBAAmB;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,KAAK,WAAW,GACZ,MAAM,GACN;IAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAYzD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,mBAAmB,GACvB,OAAO,CAAC,WAAW,CAAC,CAetB"}
+{"version":3,"file":"cli-setup.d.ts","sourceRoot":"","sources":["../src/cli-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAiCH;;;;;GAKG;AACH,UAAU,eAAe;IACvB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,UAAU,gBAAgB;IACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAobD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmDhE"}

package/dist/cli-setup.js

@@ -1,146 +1,397 @@
 /**
- * CLI Setup Path — Device Code Flow via terminal prompts.
+ * CLI Login Path — OAuth 2.0 Device Authorization Grant (RFC 8628).
  *
- * Implements `configureInteractive()` hook for OpenClaw's
- * `openclaw channels login --channel agent-network` command.
+ * Implements `login()` hook for OpenClaw's 2026.4.x channel-plugin contract:
+ *     api.registerChannel({ plugin: { ..., auth: { login } } })
  *
- * Follows the WhatsApp channel pattern: CLI displays a code,
- * user authorizes in browser, credentials are returned to OpenClaw
- * which persists them to openclaw.json.
+ * Invoked by `openclaw channels login --channel agent-network`. CLI dispatch
+ * at `dist/channels-cli-Cc40S0aS.js:85` reads `plugin.auth?.login` and throws
+ * `"Channel ... does not support login"` if absent. See WhatsApp + Feishu
+ * bundled extensions for reference implementations of the same contract.
  *
+ * Flow:
+ *   1. POST {idpBaseUrl}/api/auth/device/code  with client_id + scope
+ *      → display user_code + verification_uri to the user
+ *   2. Poll {idpBaseUrl}/api/auth/device/token until access_token issued
+ *      → handles `expired_token`, `authorization_pending`, `slow_down`
+ *   3. POST {apiHost}/runtime/v1/onboard  with Bearer access_token
+ *      → list / select existing agent / create new (terminal prompter)
+ *   4. Persist credentials directly via `writeCredentials()` into
+ *      `openclaw.json`. (The CLI does NOT auto-persist after login returns —
+ *      unlike the legacy `configureInteractive` contract — so the plugin
+ *      owns the file write; see `runChannelLogin` in channels-cli source.)
+ *
+ * History. Pre-migration this file existed as a `setup_codes`-based bespoke
+ * flow (deleted in fd5568e8). A device-flow re-implementation landed in 0.5.0
+ * under `configureInteractive` mounted at `plugin.setup.configureInteractive`
+ * — but that mount path is not read by any known OpenClaw version (neither
+ * 2026.3.x's top-level `plugin.configureInteractive` nor 2026.4.x's
+ * `plugin.auth.login`). 0.5.1 corrects the mount point and adopts the
+ * 2026.4.x `{cfg, accountId, runtime, verbose, channelInput}` signature.
+ *
+ * See #1264 for the design rationale (single-driver Node semantic — re-running
+ * this flow rotates the api_key and evicts any previously-connected Runtime).
  */
-import { DEFAULT_API_HOST, initSetup, listAgents, onboard, PlatformApiError, pollSetup, reconnect, SetupExpiredError, SetupPendingError, } from "./platform-client.js";
+import { cancel, confirm as clackConfirm, select as clackSelect, text as clackText, isCancel, } from "@clack/prompts";
+import { writeCredentials } from "./config.js";
+import { DEFAULT_API_HOST, onboard, PlatformApiError, } from "./platform-client.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const CREATE_NEW_OPTION = "Create new agent";
-// ---------------------------------------------------------------------------
-// Implementation
-// ---------------------------------------------------------------------------
 /**
- * Interactive Device Code Flow for OpenClaw CLI.
+ * Better Auth IdP base URL. Default targets the preview environment.
  *
- * Called by `openclaw channels login --channel agent-network` or the onboarding wizard.
- * Returns `{ cfg, accountId }` — OpenClaw CLI handles writing to openclaw.json.
+ * TODO: flip to the production URL when W8 (api.masons.ai consolidation)
+ * lands. Plugins shipped with this default before that flip will still
+ * work — the user can override by setting `idpBaseUrl` in their
+ * `openclaw.json` channel config (or by re-running setup which writes
+ * whatever is current).
  */
-export async function configureInteractive(ctx) {
-    const { prompter } = ctx;
-    // Resolve API host from existing config or default
-    const apiHost = typeof ctx.cfg.apiHost === "string" ? ctx.cfg.apiHost : DEFAULT_API_HOST;
-    const cfg = { apiHost };
-    // --- Phase 1: Device Code Flow (init + authorize + poll) ---
-    const setupToken = await deviceCodeFlow(cfg, prompter);
-    // --- Phase 2: Agent selection or creation ---
-    const finalCreds = await agentSetup(cfg, setupToken, prompter);
-    return buildResult(finalCreds.connectorUrl, finalCreds.token, apiHost);
+const DEFAULT_IDP_BASE_URL = "https://preview.masons.ai";
+/**
+ * OAuth client_id registered for OpenClaw at the IdP — see
+ * `apps/web/scripts/seed.ts`. Hardcoded because there's only one OpenClaw
+ * client today; if multiple wrappers (e.g. self-hosted vs Claude Desktop
+ * variant) ever need distinct client_ids, expose this via the channel
+ * config schema.
+ */
+const OAUTH_CLIENT_ID = "openclaw";
+/**
+ * Scopes requested at device-flow initiation. `openid` + `profile` + `email`
+ * are the standard OIDC scopes; `offline_access` requests a refresh token
+ * (Better Auth uses session tokens here, not OAuth opaque tokens — the
+ * scope is mostly indicative). Stays in sync with the scopes registered on
+ * the `oauthProvider` plugin at apps/web/lib/auth.ts.
+ */
+const SCOPE = "openid profile email offline_access";
+/** Default polling interval if the IdP does not return one. */
+const DEFAULT_POLL_INTERVAL_S = 5;
+const CREATE_NEW_OPTION = "Create new agent";
+// Handle pre-validation regex — strict subset of the server's authoritative
+// `validateHandle` (packages/db/src/utils/handle-validation.ts:3). Used to
+// fail-fast in the terminal before round-tripping the server. Kept inline
+// because the published npm plugin can't import @workspace/db.
+//
+// Server contract: `/^[a-z][a-z0-9_-]{2,14}$/` against the lowercased input.
+// MUST be a strict subset (false-negatives OK, false-positives forbidden) —
+// otherwise the user sees "passed client check" then "server rejected" for
+// the same input, which is confusing.
+//
+// Reserved-handle check (e.g., "masons", "openclaw") is server-only — too
+// volatile for the plugin to track; the round-trip is acceptable for that.
+const HANDLE_REGEX = /^[a-z][a-z0-9_-]{2,14}$/;
+class DeviceFlowError extends Error {
+}
+class DeviceFlowExpired extends Error {
 }
-// ---------------------------------------------------------------------------
-// Device Code Flow
-// ---------------------------------------------------------------------------
 /**
- * Run the Device Code Flow loop. Returns an authorized setup token.
- * Handles code expiration by restarting with a fresh init.
+ * User pressed Ctrl+C at any prompter step. Subclass of `DeviceFlowError`
+ * so the existing throw/catch chain still works, but distinguished so the
+ * `login` handler can skip the redundant `runtime.error` call (clack's
+ * `cancel()` already emitted the canonical "cancelled" UI).
  */
-async function deviceCodeFlow(cfg, prompter) {
+class CancelError extends DeviceFlowError {
+}
+/**
+ * Run the RFC 8628 device flow loop. Returns the access_token on success.
+ * On expiration, restarts the loop transparently (user gets a fresh code).
+ */
+async function deviceCodeFlow(idpBaseUrl, prompter) {
     for (;;) {
-        const initResult = await initSetup(cfg);
-        // Display setup code and authorization link.
-        // Uses prompter.text() as a "press Enter to continue" prompt —
-        // OpenClaw's prompter has no display-only method, so text() with
-        // discarded input is the established pattern (see WhatsApp channel).
+        const init = await initDeviceCode(idpBaseUrl);
         await prompter.text([
             "",
-            `Setup code: ${initResult.setup_code}`,
+            `Setup code: ${init.user_code}`,
             "",
-            `Open this link to authorize: ${initResult.verification_uri}`,
+            `Open this link to authorize: ${init.verification_uri_complete ?? `${init.verification_uri}?user_code=${init.user_code}`}`,
             "",
             "Press Enter after you've authorized in the browser",
         ].join("\n"));
-        // Poll until authorized or expired
-        const pollResult = await pollUntilAuthorized(cfg, initResult.setup_token, prompter);
-        if (pollResult === "expired") {
-            continue;
+        try {
+            const accessToken = await pollUntilAuthorized(idpBaseUrl, init.device_code, init.interval ?? DEFAULT_POLL_INTERVAL_S, prompter);
+            return accessToken;
+        }
+        catch (err) {
+            if (err instanceof DeviceFlowExpired) {
+                await prompter.text("Setup code expired. Press Enter for a new one.");
+                continue;
+            }
+            throw err;
         }
-        return pollResult.setup_token;
     }
 }
-async function pollUntilAuthorized(cfg, setupToken, prompter) {
+async function initDeviceCode(idpBaseUrl) {
+    const params = new URLSearchParams();
+    params.set("client_id", OAUTH_CLIENT_ID);
+    params.set("scope", SCOPE);
+    const res = await fetch(`${idpBaseUrl}/api/auth/device/code`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: params.toString(),
+    });
+    if (!res.ok) {
+        // 4xx at initiation → likely a misconfigured client_id or scope. Surface
+        // a clear message rather than retrying — this is a setup error, not a
+        // transient one.
+        const body = (await res.json().catch(() => ({})));
+        const code = typeof body.error === "string" ? body.error : "unknown";
+        const description = typeof body.error_description === "string"
+            ? body.error_description
+            : `IdP returned ${res.status}`;
+        throw new DeviceFlowError(`Device code initiation failed (${code}): ${description}. ` +
+            `Verify that "${OAUTH_CLIENT_ID}" is registered with the device_code grant ` +
+            `and is in the deviceAuthorization plugin's allowlist at the IdP.`);
+    }
+    return (await res.json());
+}
+async function pollUntilAuthorized(idpBaseUrl, deviceCode, intervalSeconds, prompter) {
+    let interval = intervalSeconds;
     for (;;) {
-        try {
-            const result = await pollSetup(cfg, setupToken);
-            return result;
+        const params = new URLSearchParams();
+        params.set("grant_type", "urn:ietf:params:oauth:grant-type:device_code");
+        params.set("device_code", deviceCode);
+        params.set("client_id", OAUTH_CLIENT_ID);
+        const res = await fetch(`${idpBaseUrl}/api/auth/device/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: params.toString(),
+        });
+        if (res.ok) {
+            const success = (await res.json());
+            return success.access_token;
         }
-        catch (err) {
-            if (err instanceof SetupExpiredError) {
-                await prompter.text("Setup code expired. Press Enter to generate a new one.");
-                return "expired";
+        const body = (await res.json().catch(() => ({})));
+        if (body.error === "authorization_pending") {
+            // User hasn't approved yet — wait and ask if they want to continue.
+            const retry = await prompter.confirm("Not authorized yet. Have you entered the code in your browser?");
+            if (!retry) {
+                // User gave up on this code — same recovery as expiration: ask
+                // the outer loop to restart with a fresh code. Throwing
+                // DeviceFlowExpired (rather than a separate "abandoned" sentinel)
+                // is intentional — both paths recover identically.
+                throw new DeviceFlowExpired();
             }
-            if (err instanceof SetupPendingError) {
-                const retry = await prompter.confirm("Not authorized yet. Have you entered the code in your browser?");
-                if (!retry) {
-                    return "expired"; // User gave up — treat as restart
-                }
-                continue;
-            }
-            throw err; // Unexpected error — propagate
+            await sleep(interval * 1000);
+            continue;
+        }
+        if (body.error === "slow_down") {
+            // RFC 8628 §3.5 — server requests we slow down. Bump interval +5s.
+            interval += 5;
+            await sleep(interval * 1000);
+            continue;
         }
+        if (body.error === "expired_token") {
+            throw new DeviceFlowExpired();
+        }
+        if (body.error === "access_denied") {
+            throw new DeviceFlowError("Authorization was denied. Re-run setup if this was a mistake.");
+        }
+        // Unknown error — bail with whatever we got from the server.
+        throw new DeviceFlowError(`Device token poll failed: ${body.error ?? "unknown"} ` +
+            `(${body.error_description ?? "no description"})`);
     }
 }
-async function agentSetup(cfg, setupToken, prompter) {
-    const { agents } = await listAgents(cfg, setupToken);
-    if (agents.length > 0) {
-        // User has existing agents — let them choose or create new
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+// ---------------------------------------------------------------------------
+// Onboard (agent select / create)
+// ---------------------------------------------------------------------------
+async function agentSetup(apiHost, accessToken, prompter) {
+    const platformCfg = { apiHost };
+    // First call: empty body. The server's list mode is intentionally
+    // non-mutating — it returns 412 (no agents) or 422 (here are your agents,
+    // pick one). Rotation only happens on the explicit `{agentId}` call after
+    // the user picks. Even with a single agent, the picker shows so the user
+    // explicitly confirms before any existing Runtime is evicted.
+    const listResult = await onboard(platformCfg, accessToken, {});
+    if (listResult.kind === "ok") {
+        // List mode never returns 200 by contract. If a future server version
+        // changes that, surface explicitly rather than silently accepting a
+        // rotation the user didn't confirm.
+        throw new DeviceFlowError("Server returned an unexpected 200 from the list call — refusing " +
+            "to use it without explicit user selection. Please report this.");
+    }
+    if (listResult.data.code === "no_agents") {
+        // Zero agents — prompt for handle to create one.
+        return await createAgentLoop(platformCfg, accessToken, prompter);
+    }
+    if (listResult.data.code === "agent_required") {
+        // Show picker. Single-agent case still goes through the picker (one
+        // agent + "Create new" choice) so the user explicitly confirms which
+        // agent this Runtime is claiming. The selection triggers api_key
+        // rotation — see "single-driver Node semantic" in CHANGELOG.
+        const agents = listResult.data.agents;
         const choices = [
-            ...agents.map((a) => `${a.handle} (${a.address})`),
+            ...agents.map((a) => a.name ? `@${a.handle} (${a.name})` : `@${a.handle}`),
             CREATE_NEW_OPTION,
         ];
-        const selected = await prompter.select("You already have agent(s). Choose one to reconnect or create new:", choices);
-        if (selected !== CREATE_NEW_OPTION) {
-            // Find the selected agent and reconnect
-            const idx = choices.indexOf(selected);
-            const agent = agents[idx];
-            if (agent) {
-                const result = await reconnect(cfg, setupToken, agent.id);
-                return { connectorUrl: result.connectorUrl, token: result.token };
-            }
+        const promptLabel = agents.length === 1
+            ? "You have one agent. Confirm to claim it for this Runtime " +
+                "(its api_key will be rotated; any previously-connected Runtime " +
+                "for this agent will be disconnected):"
+            : "You have multiple agents. Pick one to claim for this Runtime " +
+                "(its api_key will be rotated; any previously-connected Runtime " +
+                "for the chosen agent will be disconnected):";
+        const selected = await prompter.select(promptLabel, choices);
+        if (selected === CREATE_NEW_OPTION) {
+            return await createAgentLoop(platformCfg, accessToken, prompter);
+        }
+        const idx = choices.indexOf(selected);
+        const agent = agents[idx];
+        if (!agent) {
+            throw new DeviceFlowError("Picker returned an unrecognized choice. Please re-run setup.");
         }
+        const selectResult = await onboard(platformCfg, accessToken, {
+            agentId: agent.id,
+        });
+        if (selectResult.kind !== "ok") {
+            throw new DeviceFlowError(`Agent selection failed: ${selectResult.data.code}`);
+        }
+        return selectResult.data;
     }
-    // Create new agent
-    return createAgent(cfg, setupToken, prompter);
+    // invalid_handle / handle_taken can only happen on a `create` call —
+    // not from an empty `{}` first call.
+    throw new DeviceFlowError(`Unexpected onboard error on initial list call: ${listResult.data.code}`);
 }
-async function createAgent(cfg, setupToken, prompter) {
+async function createAgentLoop(platformCfg, accessToken, prompter) {
     for (;;) {
-        const handle = await prompter.text("Choose a handle for your Agent (3-15 chars, lowercase letters, numbers, hyphens, underscores):");
-        try {
-            const result = await onboard(cfg, setupToken, { handle: handle.trim() });
-            return { connectorUrl: result.connectorUrl, token: result.token };
+        const handle = await prompter.text("Choose a handle for your Agent (3-15 chars, start with a letter, then letters/numbers/hyphens/underscores):");
+        // Lowercase + trim mirrors the server's normalizeHandle step. If the user
+        // typed "Alice", we test "alice" against the regex — same outcome the
+        // server would produce. Prevents the false-negative case where a valid
+        // handle is rejected client-side just for case.
+        const normalized = handle.trim().toLowerCase();
+        // Client-side fail-fast — saves a server round-trip on obvious mistakes.
+        // Server's validateHandle is the authoritative source for both format
+        // and the reserved-handle list.
+        if (!HANDLE_REGEX.test(normalized)) {
+            await prompter.text(`"${handle}" must be 3-15 chars, start with a letter, then only letters/numbers/hyphens/underscores. Press Enter to try again.`);
+            continue;
         }
-        catch (err) {
-            if (err instanceof PlatformApiError) {
-                if (err.code === "handle_taken") {
-                    await prompter.text(`"${handle}" is already taken. Press Enter to try another.`);
-                    continue;
-                }
-                if (err.code === "invalid_handle") {
-                    await prompter.text(`"${handle}" is not valid. Use 3-15 lowercase letters, numbers, hyphens, or underscores. Press Enter to try again.`);
-                    continue;
-                }
-            }
-            throw err; // Unexpected error — propagate
+        const result = await onboard(platformCfg, accessToken, {
+            create: { handle: normalized },
+        });
+        if (result.kind === "ok") {
+            return result.data;
+        }
+        if (result.data.code === "handle_taken") {
+            await prompter.text(`"${normalized}" is already taken. Press Enter to try another.`);
+            continue;
+        }
+        if (result.data.code === "invalid_handle") {
+            await prompter.text(`"${normalized}" failed server validation: ${result.data.message}. Press Enter to try again.`);
+            continue;
         }
+        // Other structured errors shouldn't reach here on a create call —
+        // surface with whatever we got.
+        throw new DeviceFlowError(`Unexpected onboard error on create: ${result.data.code}`);
     }
 }
 // ---------------------------------------------------------------------------
-// Result builder
+// Clack-backed Prompter adapter
 // ---------------------------------------------------------------------------
-function buildResult(connectorUrl, token, apiHost) {
+/**
+ * Build a Prompter backed by `@clack/prompts` (the same library OpenClaw CLI
+ * uses internally, so the terminal UX is consistent with other channel
+ * plugins). Cancel sentinels (user Ctrl+C) are mapped to `DeviceFlowError`
+ * so the login function can treat cancels as a clean exit condition.
+ */
+function createClackPrompter() {
+    const abortOnCancel = (result) => {
+        if (isCancel(result)) {
+            // Emit clack's canonical cancel UI (bracketed red "cancelled") here so
+            // the user sees a clean exit indicator, then throw `CancelError` so the
+            // outer `login` catch returns silently (avoids printing the same line
+            // twice — UI from `cancel()` + a redundant `runtime.error` afterwards).
+            cancel("Setup cancelled.");
+            throw new CancelError("Setup cancelled by user.");
+        }
+    };
     return {
-        cfg: {
-            accounts: {
-                default: { connectorUrl, token },
-            },
-            apiHost,
+        async text(label) {
+            // `text(label, opts?.default)` previously mapped `opts.default` to clack's
+            // `placeholder` — but clack's `placeholder` is hint-only (not auto-submitted
+            // on empty input), and no current caller passes `opts.default`. Dropped
+            // the mapping until a real default-value need surfaces; revisit by
+            // implementing `clackText({ message, defaultValue })` then.
+            const result = await clackText({ message: label });
+            abortOnCancel(result);
+            return result;
+        },
+        async confirm(label) {
+            const result = await clackConfirm({ message: label });
+            abortOnCancel(result);
+            return result;
+        },
+        async select(label, choices) {
+            // Narrow the generic — we use `string` values throughout the flow.
+            const result = await clackSelect({
+                message: label,
+                options: choices.map((choice) => ({ value: choice, label: choice })),
+            });
+            abortOnCancel(result);
+            return result;
         },
-        accountId: "default",
     };
 }
+// ---------------------------------------------------------------------------
+// Public hook — `plugin.auth.login` (OpenClaw 2026.4.x contract)
+// ---------------------------------------------------------------------------
+/**
+ * Channel login hook — invoked by `openclaw channels login --channel agent-network`.
+ *
+ * Unlike the legacy `configureInteractive` contract (which returned a config
+ * object for the CLI to persist), the 2026.4.x `auth.login` contract returns
+ * void and expects the plugin to persist any config changes itself. We use
+ * `writeCredentials()` in config.ts, which writes `openclaw.json` atomically
+ * and bumps the state-cache generation so Layer B's dynamic context re-reads
+ * on the next turn.
+ *
+ * Errors during device flow or onboarding are surfaced via `ctx.runtime.error`
+ * (not thrown) so OpenClaw CLI doesn't display a stack trace — matches the
+ * WhatsApp/Feishu pattern.
+ */
+export async function login(ctx) {
+    // Channel-level config (`cfg.apiHost`, `cfg.idpBaseUrl`) — both have
+    // defaults. Existing values from openclaw.json are preserved on re-run.
+    const apiHost = typeof ctx.cfg.apiHost === "string" ? ctx.cfg.apiHost : DEFAULT_API_HOST;
+    const idpBaseUrl = typeof ctx.cfg.idpBaseUrl === "string"
+        ? ctx.cfg.idpBaseUrl
+        : DEFAULT_IDP_BASE_URL;
+    const prompter = createClackPrompter();
+    let creds;
+    try {
+        const accessToken = await deviceCodeFlow(idpBaseUrl, prompter);
+        creds = await agentSetup(apiHost, accessToken, prompter);
+    }
+    catch (err) {
+        if (err instanceof CancelError) {
+            // User pressed Ctrl+C. The clack `cancel()` call inside the prompter
+            // adapter already emitted the cancellation UI; nothing else to print.
+            return;
+        }
+        if (err instanceof DeviceFlowError) {
+            // Device-flow / onboard error with a human-friendly message.
+            // Print and return cleanly — CLI shows nothing else on a return.
+            ctx.runtime.error(err.message);
+            return;
+        }
+        if (err instanceof PlatformApiError) {
+            ctx.runtime.error(`Onboard failed (HTTP ${err.status} ${err.code}): ${err.message}`);
+            return;
+        }
+        // Unknown error — let CLI surface the stack. Surfaces platform bugs
+        // that aren't covered by our structured error types.
+        throw err;
+    }
+    // Persist: `openclaw.json` schema for an account is `{connectorUrl, token}`
+    // (see config-schema.ts). On the wire the onboard response field is
+    // `apiKey` to disambiguate from OAuth "session token" / JWT — but locally
+    // on disk it's persisted as `token` for backward compatibility with the
+    // existing `channel.resolveAccount()` reader.
+    await writeCredentials({ connectorUrl: creds.connectorUrl, token: creds.apiKey }, apiHost, idpBaseUrl);
+    ctx.runtime.log(`✓ Connected as @${creds.handle}`);
+}

package/dist/config.d.ts

@@ -160,12 +160,16 @@ export interface NetworkCredentials {
     token: string;
 }
 /**
- * Write credentials + apiHost to `openclaw.json`.
+ * Write credentials + apiHost (+ optional idpBaseUrl) to `openclaw.json`.
  *
- * Atomic: credentials and apiHost are written in a single operation
- * to avoid partial-write race conditions.
+ * Atomic: all fields are written in a single persistConfig() call to avoid
+ * partial-write race conditions.
+ *
+ * `idpBaseUrl` is written only when provided, mirroring `apiHost`'s pattern —
+ * omitted values leave any existing field in place (useful when callers want
+ * to refresh credentials without overriding IdP URL).
  */
-export declare function writeCredentials(creds: NetworkCredentials, apiHost?: string): Promise<void>;
+export declare function writeCredentials(creds: NetworkCredentials, apiHost?: string, idpBaseUrl?: string): Promise<void>;
 /**
  * Write pending connection target handle.
  *