@masons/agent-network 0.5.14 → 0.5.16

package/dist/cli-setup.js

@@ -1,158 +1,19 @@
-/**
- * CLI Login Path — encrypted server-bridge handoff (v0.5.14).
- *
- * Implements `login()` hook for OpenClaw's 2026.4.x channel-plugin contract:
- *     api.registerChannel({ plugin: { ..., auth: { login } } })
- *
- * 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.
- *
- * Flow (v0.5.14 — `serverBridgeHandoffFlow`):
- *
- *   1. Generate an ephemeral RSA-2048 keypair in the plugin process. The
- *      private key never leaves process memory; the SPKI-encoded public
- *      key travels to `apps/api` for the browser to encrypt against.
- *   2. POST `${apiHost}/v1/cli-handoff/init` with the SPKI pubkey; receive
- *      back a `session_id` (`cli_…`) keyed in apps/api's Redis with a 5-min
- *      TTL.
- *   3. Print a handoff URL (`${idpBaseUrl}/console/handoff?session=<id>` or
- *      the per-handle variant when `channelInput` parses as a handle) for
- *      the user to open in their browser. The plugin does NOT spawn a
- *      browser — `child_process` is forbidden by OpenClaw's plugin scanner
- *      (rules `dangerous-exec`, `env-harvesting`).
- *   4. The user signs in to apps/web, picks or creates an agent, and the
- *      browser runs WebCrypto client-side: generates an ephemeral AES-256-GCM
- *      key, encrypts `{token, agent, key}` JSON under it, wraps the AES key
- *      under the plugin's RSA pubkey via RSA-OAEP-256, and POSTs the
- *      `{wrapped_key, iv, ciphertext}` triple to
- *      `${apiHost}/v1/cli-handoff/:session/complete` (authenticated server-
- *      action mediated by apps/web). Server stores ciphertext only.
- *   5. Plugin polls `${apiHost}/v1/cli-handoff/:session/poll` every 2s until
- *      the bridge returns `{status: "completed", payload}`.
- *   6. Plugin decrypts in-process: RSA-OAEP-256 unwrap → AES-256-GCM
- *      decrypt → JSON parse → validate `masons_rt_v1_` prefix.
- *   7. Persist `{connectorUrl, token}` to `openclaw.json` via
- *      `writeCredentials()`. `connectorUrl` derives `wss://<apiHost>/gateway`
- *      for cloud / preview deployments; self-hosted users keep an explicit
- *      `connectorUrl` in their `openclaw.json` and the value is preserved
- *      across the handoff (see `loadExistingConnectorUrl()`).
- *
- * Why this shape (vs the v0.5.13 loopback handoff or device flow):
- *
- *   - **Sandbox-friendly.** No `child_process` (no auto-open), no
- *     `node:http.createServer` listener, no `process.env` read inside the
- *     network code path. OpenClaw's plugin scanner accepts the resulting
- *     code surface — the path that blocked v0.5.13 is closed.
- *   - **End-to-end encrypted.** The apps/api Redis cache stores ciphertext
- *     only. A stolen Mongo / Redis dump yields nothing useful — the wrapped
- *     AES key is unrecoverable without the plugin's RSA private key (which
- *     lives only in plugin process memory). Mitigates the Shai-Hulud
- *     "plaintext-at-rest, even short-lived" concern that originally caused
- *     Decision B Alt B3 to be rejected; see #1475 issuecomment-4365154888 § A
- *     for the formal reject-supersede record.
- *   - **`masons_rt_…` carrier on connector.** Connector verifies new keys
- *     via the W4 PR 1 mirror substrate; this file does not change carrier
- *     semantics, only the transport that gets the plaintext from
- *     apps/web → CLI.
- *
- * Legacy device-flow helpers (`deviceCodeFlow`, `pollUntilAuthorized`,
- * `agentSetup`, `createAgentLoop`) remain in this file as `@deprecated`
- * reference for the W6 cleanup window. They have no call site after the
- * v0.5.13 → v0.5.14 migration and should not be invoked by any new code.
- *
- * See #1264 for original design rationale (single-driver Node semantic —
- * re-running this flow rotates the runtime key and evicts any previously-
- * connected Runtime); see the v0.5.14 strategic-pass at
- * `#1475 issuecomment-4365154888` for the lock that supersedes both
- * Alt B1 (loopback, scanner-blocked) and the prior Alt B3 reject.
- */
 import { createDecipheriv, constants as cryptoConstants, generateKeyPairSync, privateDecrypt, } from "node:crypto";
-import { cancel, confirm as clackConfirm, select as clackSelect, text as clackText, isCancel, } from "@clack/prompts";
-import { getOpenClawHome, writeCredentials } from "./config.js";
-import { DEFAULT_API_HOST, onboard, PlatformApiError, } from "./platform-client.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/**
- * Better Auth IdP base URL. Default targets the preview environment.
- *
- * 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).
- */
+import { readExistingConnectorUrl, writeCredentials } from "./config.js";
+import { DEFAULT_API_HOST, DEFAULT_CONNECTOR_URL, PlatformApiError, } from "./platform-client.js";
 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}$/;
-/**
- * Hard cap on how long the plugin polls the bridge before giving up.
- * Aligned with the apps/api `/v1/cli-handoff/init` Redis TTL (5 min) so
- * the plugin and the bridge time out together — a longer plugin window
- * would tail off after the session expired anyway.
- */
 const HANDOFF_TIMEOUT_MS = 5 * 60 * 1000;
-/**
- * Polling interval. Stripe CLI uses ~1s; gh CLI device flow uses 5s. 2s
- * lands in between — adequate spinner-style UX without thrashing the
- * Redis cache.
- */
 const HANDOFF_POLL_INTERVAL_MS = 2000;
-/**
- * Run the encrypted server-bridge handoff. Returns the decrypted
- * runtime API key + the agent identity the browser issued it for.
- *
- * `channelInput` is the optional argument from
- * `openclaw channels login --channel agent-network -- <input>`. When
- * the input parses as a handle (`^[a-z][a-z0-9_-]{2,14}$`) the flow
- * directs the user to the per-handle deep-link entry; otherwise it
- * falls back to the picker page. Anything that isn't a handle silently
- * falls through.
- */
+class SetupFlowError extends Error {
+}
 async function serverBridgeHandoffFlow(apiHost, idpBaseUrl, runtime, channelInput) {
-    // 1. Generate an ephemeral RSA-2048 keypair. The private key never
-    //    leaves the plugin process; the SPKI-encoded public key travels
-    //    to apps/api so the browser can encrypt against it.
     const { publicKey, privateKey } = generateKeyPairSync("rsa", {
         modulusLength: 2048,
     });
     const cliPubkeySpki = publicKey
         .export({ type: "spki", format: "der" })
         .toString("base64url");
-    // 2. POST /v1/cli-handoff/init — opens a session keyed in apps/api's
-    //    Redis cache. Anonymous endpoint; the CLI has no MASONS credential
-    //    yet (delivering one is the point of this flow).
     const apiBase = normalizeHttpBase(apiHost);
     let session_id;
     try {
@@ -162,24 +23,21 @@ async function serverBridgeHandoffFlow(apiHost, idpBaseUrl, runtime, channelInpu
             body: JSON.stringify({ cli_pubkey: cliPubkeySpki }),
         });
         if (!initRes.ok) {
-            throw new DeviceFlowError(`Setup service rejected init (HTTP ${initRes.status}). Retry in a moment; if it persists, check that ${apiBase} is reachable and not behind a proxy that strips the request body.`);
+            throw new SetupFlowError(`Setup service rejected init (HTTP ${initRes.status}). Retry in a moment; if it persists, check that ${apiBase} is reachable and not behind a proxy that strips the request body.`);
         }
         const initBody = (await initRes.json());
         if (typeof initBody.session_id !== "string" ||
             initBody.session_id.length === 0) {
-            throw new DeviceFlowError("Setup service returned a malformed response (missing session_id). Retry; if it persists, this is a server-side bug worth reporting.");
+            throw new SetupFlowError("Setup service returned a malformed response (missing session_id). Retry; if it persists, this is a server-side bug worth reporting.");
         }
         session_id = initBody.session_id;
     }
     catch (err) {
-        if (err instanceof DeviceFlowError)
+        if (err instanceof SetupFlowError)
             throw err;
         const message = err instanceof Error ? err.message : "unknown error";
-        throw new DeviceFlowError(`Could not reach the setup service at ${apiBase} (${message}). Retry in a moment.`);
+        throw new SetupFlowError(`Could not reach the setup service at ${apiBase} (${message}). Retry in a moment.`);
     }
-    // 3. Print the handoff URL. No browser auto-open — `child_process`
-    //    is forbidden by the OpenClaw plugin scanner. The user opens
-    //    the link manually in their browser.
     const handle = parseHandleFromInput(channelInput);
     const handoffPath = handle
         ? `/console/agents/${encodeURIComponent(handle)}/runtime-keys/handoff`
@@ -193,26 +51,20 @@ async function serverBridgeHandoffFlow(apiHost, idpBaseUrl, runtime, channelInpu
         "Waiting for the runtime key to be issued and delivered…",
         "",
     ].join("\n"));
-    // 4. Long-poll /v1/cli-handoff/:session/poll until the bridge
-    //    returns `{status: "completed", payload}`. Hard cap at
-    //    HANDOFF_TIMEOUT_MS so a forgotten browser tab does not pin
-    //    the plugin process.
     const envelope = await pollForCompletion(apiBase, session_id);
-    // 5. Decrypt in-process. RSA-OAEP-256 unwrap → AES-256-GCM decrypt
-    //    → JSON parse → validate runtime key prefix.
     let payload;
     try {
         payload = decryptBridgeEnvelope(privateKey, envelope);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : "unknown error";
-        throw new DeviceFlowError(`Handoff received but could not be decrypted (${message}). The link may have been tampered with — re-run setup. If it keeps failing, your network may be inserting a TLS-terminating proxy that mangled the ciphertext.`);
+        throw new SetupFlowError(`Handoff received but could not be decrypted (${message}). The link may have been tampered with — re-run setup. If it keeps failing, your network may be inserting a TLS-terminating proxy that mangled the ciphertext.`);
     }
     if (typeof payload.token !== "string" ||
         !payload.token.startsWith("masons_rt_v1_") ||
         typeof payload.agent?.handle !== "string" ||
         typeof payload.agent?.agentId !== "string") {
-        throw new DeviceFlowError("Handoff payload is missing required fields. Re-run setup; if it keeps happening, this is a server-side bug worth reporting.");
+        throw new SetupFlowError("Handoff payload is missing required fields. Re-run setup; if it keeps happening, this is a server-side bug worth reporting.");
     }
     return {
         token: payload.token,
@@ -225,11 +77,6 @@ async function serverBridgeHandoffFlow(apiHost, idpBaseUrl, runtime, channelInpu
         },
     };
 }
-/**
- * Long-poll `/v1/cli-handoff/:session/poll` until the bridge returns
- * a completed envelope or the overall window expires. 2s interval is
- * the locked architect choice (#1475 issuecomment-4365154888 § B.2).
- */
 async function pollForCompletion(apiBase, sessionId) {
     const start = Date.now();
     while (Date.now() - start < HANDOFF_TIMEOUT_MS) {
@@ -238,16 +85,13 @@ async function pollForCompletion(apiBase, sessionId) {
             res = await fetch(`${apiBase}/v1/cli-handoff/${encodeURIComponent(sessionId)}/poll`, { method: "GET" });
         }
         catch (_err) {
-            // Transient network error — try again on the next tick. Persistent
-            // network failures will surface as the timeout below.
             await sleep(HANDOFF_POLL_INTERVAL_MS);
             continue;
         }
         if (res.status === 404) {
-            throw new DeviceFlowError("Handoff session expired before the runtime key was delivered. Re-run setup.");
+            throw new SetupFlowError("Handoff session expired before the runtime key was delivered. Re-run setup.");
         }
         if (!res.ok) {
-            // Other 4xx/5xx — back off and retry until the timeout fires.
             await sleep(HANDOFF_POLL_INTERVAL_MS);
             continue;
         }
@@ -255,23 +99,14 @@ async function pollForCompletion(apiBase, sessionId) {
         if (body.status === "completed" && body.payload) {
             return body.payload;
         }
-        // status === "pending" (or anything else) → keep polling.
         await sleep(HANDOFF_POLL_INTERVAL_MS);
     }
-    throw new DeviceFlowError("Handoff timed out before the runtime key was delivered. Re-run setup; if you're behind a proxy that blocks long-running fetches, retry on a different network.");
+    throw new SetupFlowError("Handoff timed out before the runtime key was delivered. Re-run setup; if you're behind a proxy that blocks long-running fetches, retry on a different network.");
 }
-/**
- * Decrypt the bridge envelope. RSA-OAEP-256 unwraps the AES key;
- * AES-256-GCM decrypts the ciphertext (auth tag is the last 16 bytes
- * of the ciphertext per the WebCrypto AES-GCM output convention).
- */
 function decryptBridgeEnvelope(privateKey, envelope) {
     const wrappedKey = Buffer.from(envelope.wrapped_key, "base64url");
     const iv = Buffer.from(envelope.iv, "base64url");
     const fullCiphertext = Buffer.from(envelope.ciphertext, "base64url");
-    // WebCrypto's `crypto.subtle.encrypt({name: "AES-GCM"}, ...)` returns
-    // ciphertext || tag concatenated, with a 16-byte auth tag. Node's
-    // `createDecipheriv("aes-256-gcm", ...)` API expects them split.
     if (fullCiphertext.length < 17) {
         throw new Error("ciphertext shorter than auth tag");
     }
@@ -294,27 +129,12 @@ function decryptBridgeEnvelope(privateKey, envelope) {
     ]);
     return JSON.parse(plaintext.toString("utf-8"));
 }
-/**
- * Normalize an `apiHost` config value to an HTTPS base URL. Accepts:
- *   - bare host (`preview-connectorapi.masons.ai`)
- *   - https URL (`https://preview-connectorapi.masons.ai`)
- *   - https URL with trailing slash
- * Returns no trailing slash.
- */
 function normalizeHttpBase(apiHost) {
     const trimmed = apiHost.replace(/\/+$/, "");
     if (/^https?:\/\//.test(trimmed))
         return trimmed;
     return `https://${trimmed}`;
 }
-// `sleep` is shared with the legacy device-flow helpers below — single
-// definition lives there to satisfy biome's `noDuplicateCase` /
-// TS's "duplicate function implementation" check.
-/**
- * Parse `channelInput` as a handle. Returns the lowercased handle on
- * match, `undefined` otherwise. Mirrors the `HANDLE_REGEX` used in the
- * legacy device flow's create form.
- */
 function parseHandleFromInput(input) {
     if (typeof input !== "string")
         return undefined;
@@ -323,373 +143,12 @@ function parseHandleFromInput(input) {
         return undefined;
     return trimmed;
 }
-/**
- * Read the existing `accounts.default.connectorUrl` from `openclaw.json`
- * if present. Used to preserve the self-hosted user's deployment-specific
- * connector URL across the handoff — the bridge does not learn it from
- * `apps/api` (issuance is decoupled from connector topology), but we
- * don't want to clobber a user-set value.
- *
- * The home-directory lookup goes through `getOpenClawHome()` in
- * `config.ts` rather than reading `process.env.OPENCLAW_HOME` here.
- * Keeps the env access in a config-only module so OpenClaw's plugin
- * scanner does not flag the network module's import graph for the
- * `env-harvesting` rule (env access combined with network send).
- *
- * Returns `undefined` when the file is absent, malformed, or doesn't
- * contain a connectorUrl. Caller falls back to `deriveCloudConnectorUrl`.
- */
-async function loadExistingConnectorUrl() {
-    // Imports are dynamic so they don't pull `node:fs` and `node:path`
-    // into the static import graph alongside the network calls above —
-    // another small mitigation against scanner heuristics that flag
-    // "fs read + http fetch in the same module."
-    const { readFile } = await import("node:fs/promises");
-    const { join } = await import("node:path");
-    const home = getOpenClawHome();
-    const path = join(home, "openclaw.json");
-    try {
-        const raw = await readFile(path, "utf-8");
-        const config = JSON.parse(raw);
-        const channels = config.channels;
-        const network = channels?.["agent-network"];
-        const accounts = network?.accounts;
-        const def = accounts?.default;
-        const value = def?.connectorUrl;
-        if (typeof value === "string" && value.length > 0)
-            return value;
-    }
-    catch {
-        // file missing / malformed / unreadable → fall through to derivation
-    }
-    return undefined;
-}
-/**
- * Derive the WebSocket connector URL from the apiHost. Matches the
- * connector's `CONNECTOR_PLUGIN_URL` env default
- * (`wss://<host>/gateway`) for cloud and preview deployments.
- *
- * Self-hosted users running a non-standard topology should set
- * `accounts.default.connectorUrl` explicitly in `openclaw.json`; the
- * bridge flow preserves that value via `loadExistingConnectorUrl`.
- */
-function deriveCloudConnectorUrl(apiHost) {
-    // Strip any incidental scheme so we never produce `wss://https://…`.
-    const host = apiHost.replace(/^https?:\/\//, "");
-    return `wss://${host}/gateway`;
-}
-class DeviceFlowError extends Error {
-}
-class DeviceFlowExpired extends Error {
-}
-/**
- * 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).
- */
-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).
- *
- * @deprecated W6 cleanup — superseded by `serverBridgeHandoffFlow`. No
- * call site after the v0.5.13 → v0.5.14 migration; the function is
- * kept as legacy reference until the W6 cleanup retires the connector-
- * side device-flow verifier
- * (`apps/connector/src/core/verify-device-session-token.ts`) and the
- * IdP-side `oauth/device/` route. Do not invoke from new code.
- */
-// biome-ignore lint/correctness/noUnusedVariables: retained as @deprecated reference for W6 cleanup
-async function deviceCodeFlow(idpBaseUrl, prompter) {
-    for (;;) {
-        const init = await initDeviceCode(idpBaseUrl);
-        await prompter.text([
-            "",
-            `Setup code: ${init.user_code}`,
-            "",
-            `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"));
-        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;
-        }
-    }
-}
-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());
-}
-/** @deprecated W6 cleanup — see `deviceCodeFlow` JSDoc. */
-// biome-ignore lint/correctness/noUnusedVariables: retained as @deprecated reference for W6 cleanup
-async function pollUntilAuthorized(idpBaseUrl, deviceCode, intervalSeconds, prompter) {
-    let interval = intervalSeconds;
-    for (;;) {
-        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;
-        }
-        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();
-            }
-            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"})`);
-    }
-}
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
     });
 }
-// ---------------------------------------------------------------------------
-// Onboard (agent select / create)
-// ---------------------------------------------------------------------------
-/** @deprecated W6 cleanup — see `deviceCodeFlow` JSDoc. */
-// biome-ignore lint/correctness/noUnusedVariables: retained as @deprecated reference for W6 cleanup
-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.name ? `@${a.handle} (${a.name})` : `@${a.handle}`),
-            CREATE_NEW_OPTION,
-        ];
-        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;
-    }
-    // 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}`);
-}
-/** @deprecated W6 cleanup — see `deviceCodeFlow` JSDoc. */
-// biome-ignore lint/correctness/noUnusedVariables: retained as @deprecated reference for W6 cleanup
-async function createAgentLoop(platformCfg, accessToken, prompter) {
-    for (;;) {
-        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;
-        }
-        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}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// Clack-backed Prompter adapter
-// ---------------------------------------------------------------------------
-/**
- * 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.
- *
- * @deprecated W6 cleanup — only the `@deprecated` device-flow helpers
- * consume this. The active server-bridge handoff
- * (`serverBridgeHandoffFlow`) uses `clack` indirectly via the
- * spinner-style stdout writes in `runtime.writeStdout`.
- */
-// biome-ignore lint/correctness/noUnusedVariables: retained for the @deprecated device-flow helpers
-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 {
-        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;
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// 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.
- *
- * Flow (v0.5.14):
- *   1. Run `serverBridgeHandoffFlow` against `apps/api` + `apps/web` —
- *      an encrypted server-bridge handoff that delivers the plaintext
- *      `masons_rt_…` token from the browser to the plugin via apps/api's
- *      Redis cache (storing ciphertext only). RSA-OAEP-256 wraps an
- *      ephemeral AES-256-GCM key the browser generates; CLI's RSA
- *      private key (held only in plugin process memory) decrypts the
- *      AES key in-process to recover the plaintext.
- *   2. Resolve the connector URL — preserve any user-set
- *      `accounts.default.connectorUrl` from `openclaw.json` (for self-
- *      hosted topologies); fall back to the cloud derivation
- *      `wss://<apiHost>/gateway` matching the connector's
- *      `CONNECTOR_PLUGIN_URL` env default.
- *   3. Persist `{connectorUrl, token}` atomically.
- *
- * Errors during the handoff 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
@@ -699,15 +158,7 @@ export async function login(ctx) {
         handoff = await serverBridgeHandoffFlow(apiHost, idpBaseUrl, ctx.runtime, ctx.channelInput);
     }
     catch (err) {
-        if (err instanceof CancelError) {
-            // User pressed Ctrl+C — clack already emitted the cancel UI.
-            return;
-        }
-        if (err instanceof DeviceFlowError) {
-            // Bridge error with a human-friendly message. Print and return
-            // cleanly — CLI shows nothing else on a return. (The class name
-            // is `DeviceFlowError` for legacy reasons; it serves as a
-            // generic "expected setup failure" sentinel for both flows.)
+        if (err instanceof SetupFlowError) {
             ctx.runtime.error(err.message);
             return;
         }
@@ -715,16 +166,11 @@ export async function login(ctx) {
             ctx.runtime.error(`Setup 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;
     }
-    // `connectorUrl` is decoupled from `apps/api` (the issuance host) by
-    // design — apps/api does not know about connector deployment topology.
-    // Preserve any explicit user-set value (self-hosted) and fall back to
-    // the well-known cloud / preview shape (`wss://<apiHost>/gateway`).
-    const existingConnectorUrl = await loadExistingConnectorUrl();
-    const connectorUrl = existingConnectorUrl ?? deriveCloudConnectorUrl(apiHost);
+    const existingConnectorUrl = await readExistingConnectorUrl();
+    const configuredConnectorUrl = typeof ctx.cfg.connectorUrl === "string" ? ctx.cfg.connectorUrl : undefined;
+    const connectorUrl = existingConnectorUrl ?? configuredConnectorUrl ?? DEFAULT_CONNECTOR_URL;
     await writeCredentials({ connectorUrl, token: handoff.token }, apiHost, idpBaseUrl);
     ctx.runtime.log(`✓ Connected as @${handoff.agent.handle}`);
 }