@masons/agent-network 0.4.26 → 0.5.0

package/dist/cli-setup.d.ts

@@ -1,13 +1,27 @@
 /**
- * CLI Setup Path — Device Code Flow via terminal prompts.
+ * CLI Setup Path — OAuth 2.0 Device Authorization Grant (RFC 8628).
  *
  * Implements `configureInteractive()` hook for OpenClaw's
  * `openclaw channels login --channel agent-network` command.
  *
- * Follows the WhatsApp channel pattern: CLI displays a code,
- * user authorizes in browser, credentials are returned to OpenClaw
- * which persists them to openclaw.json.
+ * 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. Return credentials → OpenClaw CLI persists them to openclaw.json
  *
+ * Pre-migration this file existed as a `setup_codes`-based bespoke flow
+ * (deleted in fd5568e8). This re-implementation is purely standards-based:
+ * the IdP is Better Auth's `deviceAuthorization` plugin, which speaks
+ * RFC 8628; the onboard step is a thin MASONS-specific shim that exchanges
+ * the user-scope access_token for an agent-scope api_key.
+ *
+ * See #1264 for the design rationale (in particular the "single-driver
+ * Node semantic" — re-running this flow rotates the api_key and evicts
+ * any previously-connected Runtime).
  */
 interface Prompter {
     text(label: string, opts?: {
@@ -31,7 +45,9 @@ type SetupResult = "skip" | {
 /**
  * Interactive Device Code Flow for OpenClaw CLI.
  *
- * Called by `openclaw channels login --channel agent-network` or the onboarding wizard.
+ * Called by `openclaw channels login --channel agent-network` (wired via
+ * `setup: { configureInteractive }` on the channel registration in plugin.ts).
+ *
  * Returns `{ cfg, accountId }` — OpenClaw CLI handles writing to openclaw.json.
  */
 export declare function configureInteractive(ctx: ChannelSetupContext): Promise<SetupResult>;

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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAaH,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;AA0XzD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,mBAAmB,GACvB,OAAO,CAAC,WAAW,CAAC,CA+CtB"}

package/dist/cli-setup.js

@@ -1,145 +1,325 @@
 /**
- * CLI Setup Path — Device Code Flow via terminal prompts.
+ * CLI Setup Path — OAuth 2.0 Device Authorization Grant (RFC 8628).
  *
  * Implements `configureInteractive()` hook for OpenClaw's
  * `openclaw channels login --channel agent-network` command.
  *
- * Follows the WhatsApp channel pattern: CLI displays a code,
- * user authorizes in browser, credentials are returned to OpenClaw
- * which persists them to openclaw.json.
+ * 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. Return credentials → OpenClaw CLI persists them to openclaw.json
  *
+ * Pre-migration this file existed as a `setup_codes`-based bespoke flow
+ * (deleted in fd5568e8). This re-implementation is purely standards-based:
+ * the IdP is Better Auth's `deviceAuthorization` plugin, which speaks
+ * RFC 8628; the onboard step is a thin MASONS-specific shim that exchanges
+ * the user-scope access_token for an agent-scope api_key.
+ *
+ * See #1264 for the design rationale (in particular the "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 { 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.
+ * 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(cfg, prompter) {
+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";
-            }
-            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;
+        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();
             }
-            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
+// Public hook
 // ---------------------------------------------------------------------------
-function buildResult(connectorUrl, token, apiHost) {
+/**
+ * Interactive Device Code Flow for OpenClaw CLI.
+ *
+ * Called by `openclaw channels login --channel agent-network` (wired via
+ * `setup: { configureInteractive }` on the channel registration in plugin.ts).
+ *
+ * Returns `{ cfg, accountId }` — OpenClaw CLI handles writing to openclaw.json.
+ */
+export async function configureInteractive(ctx) {
+    const { prompter } = 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;
+    let creds;
+    try {
+        const accessToken = await deviceCodeFlow(idpBaseUrl, prompter);
+        creds = await agentSetup(apiHost, accessToken, prompter);
+    }
+    catch (err) {
+        if (err instanceof DeviceFlowError) {
+            // Human-friendly surface — user reads this and re-runs setup.
+            await prompter.text(`${err.message}\n\nPress Enter to exit.`);
+            return "skip";
+        }
+        if (err instanceof PlatformApiError) {
+            await prompter.text(`Onboard failed (HTTP ${err.status} ${err.code}): ${err.message}. ` +
+                "Press Enter to exit.");
+            return "skip";
+        }
+        throw err;
+    }
+    // The openclaw.json schema for an account is { connectorUrl, token }
+    // (see config-schema.ts). On the wire the field is called `apiKey` to
+    // disambiguate from "session token" / "JWT" — but locally on disk it's
+    // persisted as `token` for backward compatibility with existing OpenClaw
+    // configs and the channel.resolveAccount() reader at channel.ts:485.
     return {
         cfg: {
             accounts: {
-                default: { connectorUrl, token },
+                default: { connectorUrl: creds.connectorUrl, token: creds.apiKey },
             },
             apiHost,
+            idpBaseUrl,
         },
         accountId: "default",
     };

package/dist/connector-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connector-client.d.ts","sourceRoot":"","sources":["../src/connector-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connector-client.d.ts","sourceRoot":"","sources":["../src/connector-client.ts"],"names":[],"mappings":"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"}

package/dist/connector-client.js

@@ -12,6 +12,13 @@ const BACKOFF_INITIAL_MS = 1_000;
 const BACKOFF_MAX_MS = 30_000;
 const ALREADY_CONNECTED_RETRY_MS = 2_000;
 const ALREADY_CONNECTED_MAX_RETRIES = 30;
+// --- Single-driver Node semantic (#1264) ---
+// The connector closes with WS code 4001 + this reason when a new Runtime
+// REGISTERs for the same agentId. The current api_key may have been rotated
+// by /runtime/v1/onboard select mode, so reconnecting with the cached token
+// is futile (would 401 forever).
+const REPLACED_BY_NEW_RUNTIME_REASON = "Replaced by new Runtime";
+const REPLACED_BY_NEW_RUNTIME_CODE = 4001;
 // --- Error class for structured errors ---
 /**
  * Error with machine-readable `code` from Connector structured errors.
@@ -146,6 +153,8 @@ export class ConnectorClient extends EventEmitter {
                 this.startRegisterTimeout();
             });
             ws.on("message", this.handleMessage);
+            // ws's "close" event passes (code, reason) — handleClose accepts both.
+            // Pass the bound arrow reference so cleanupConnection can `off()` it.
             ws.on("close", this.handleClose);
             ws.on("error", this.handleError);
         });
@@ -277,7 +286,13 @@ export class ConnectorClient extends EventEmitter {
                 this.ws?.close(4001, reason);
                 return;
             }
-            // "Already connected" — track retries for short backoff
+            // "Already connected" — track retries for short backoff.
+            // As of connector #1264 the server flips this to single-driver
+            // eviction (close code 4001 + reason "Replaced by new Runtime",
+            // handled in handleClose). The REGISTER_ACK error path with this
+            // reason is now only reachable against pre-#1264 connector
+            // deployments during a rollout window — kept for that compat,
+            // safe to remove in 0.7.0 once preview/production are upgraded.
             if (reason === "Already connected") {
                 this.alreadyConnectedRetries++;
             }
@@ -319,10 +334,36 @@ export class ConnectorClient extends EventEmitter {
         this.emit("error", new Error(`[${event.code}] ${event.message}`));
     }
     // --- Connection close ---
-    handleClose = () => {
-        dbg("connection closed intentional=%s", this.intentionalClose);
+    handleClose = (code, reason) => {
+        const reasonStr = reason
+            ? typeof reason === "string"
+                ? reason
+                : reason.toString()
+            : "";
+        dbg("connection closed code=%s reason=%s intentional=%s", code ?? "?", reasonStr, this.intentionalClose);
         const wasRegistering = this.registerReject !== null;
         this.cleanupConnection();
+        // Single-driver eviction (#1264) — connector closes us with code 4001
+        // and reason "Replaced by new Runtime" when a new REGISTER claims our
+        // agentId. The api_key we hold may have been rotated by the new
+        // Runtime's /runtime/v1/onboard call; reconnecting would 401 forever.
+        // Treat as terminal: stop reconnects, surface an actionable message,
+        // emit a distinct event so consumers (channel.ts, etc.) can react.
+        const replacedByNewRuntime = code === REPLACED_BY_NEW_RUNTIME_CODE &&
+            reasonStr === REPLACED_BY_NEW_RUNTIME_REASON;
+        if (replacedByNewRuntime) {
+            this.intentionalClose = true;
+            const msg = "This agent was claimed by another Runtime " +
+                "(api_key rotated, this Runtime disconnected). " +
+                "Re-run `openclaw channels login --channel agent-network` " +
+                "to drive this agent from here again.";
+            this.emit("error", new Error(msg));
+            if (wasRegistering) {
+                this.rejectRegister(new Error(msg));
+            }
+            this.emit("disconnected");
+            return;
+        }
         if (wasRegistering) {
             // Connection closed during REGISTER — check for special retry logic
             // (handled by rejectRegister which was already called if ACK error came first)