@masons/agent-network 0.5.12 → 0.5.13

package/dist/cli-setup.d.ts

@@ -1,5 +1,5 @@
 /**
- * CLI Login Path — OAuth 2.0 Device Authorization Grant (RFC 8628).
+ * CLI Login Path — Stripe-style browser-mediated loopback handoff.
  *
  * Implements `login()` hook for OpenClaw's 2026.4.x channel-plugin contract:
  *     api.registerChannel({ plugin: { ..., auth: { login } } })
@@ -9,28 +9,50 @@
  * `"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.)
+ * Flow (W4 PR 3 — `loopbackHandoffFlow`):
  *
- * 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.
+ *   1. Bind a one-shot HTTP listener on `127.0.0.1:0` (OS-assigned ephemeral
+ *      port). The listener serves a single `POST /handoff` plus the matching
+ *      CORS preflight, then closes.
+ *   2. Generate a 24-byte (32-char base64url) URL-safe random nonce. The
+ *      nonce travels in the URL fragment (`#nonce=…`), never the query
+ *      string — fragments do not reach `apps/web` access logs nor referer
+ *      headers (Alt W4-B2 lock).
+ *   3. Open the user's browser to the handoff URL (no-handle path uses
+ *      `${idpBaseUrl}/console/handoff?port=<port>#nonce=<nonce>`; with
+ *      `--handle` the per-handle deep-link variant is the entry).
+ *   4. The user authenticates against Better Auth on `apps/web`, picks (or
+ *      creates) an agent, and the page POSTs `{token, agent, key, nonce}`
+ *      to the listener. The listener verifies the body's `nonce` matches
+ *      the value it placed in the fragment, accepts the token, and closes.
+ *   5. Persist `{connectorUrl, token}` to `openclaw.json` via
+ *      `writeCredentials()`. `connectorUrl` is derived from `apiHost`
+ *      (`wss://<apiHost>/gateway`) for cloud / preview deployments; self-
+ *      hosted users keep an explicit `connectorUrl` in their `openclaw.json`
+ *      and the legacy value is preserved across the handoff (see
+ *      `loadExistingConnectorUrl()`).
  *
- * See #1264 for the design rationale (single-driver Node semantic — re-running
- * this flow rotates the api_key and evicts any previously-connected Runtime).
+ * Why move off device flow:
+ *
+ *   - One step shorter (no `user_code` to type into the browser).
+ *   - No periodic IdP polling (was 5s default, 5+s on `slow_down`).
+ *   - Browser remains fully authenticated across login and key issuance —
+ *     same Better Auth session is reused, so the user never re-types their
+ *     password mid-flow.
+ *   - The runtime API key carrier (`masons_rt_…`) replaces the legacy
+ *     connector-minted `sk-…` carrier; W4 PR 1 substrate plus the connector
+ *     mirror wiring earlier in this PR make both carriers verifiable through
+ *     plugin v0.5.13's life until the W6 cleanup retires the legacy path.
+ *
+ * The legacy device-flow helpers (`deviceCodeFlow`, `pollUntilAuthorized`,
+ * `agentSetup`, `createAgentLoop`) remain in this file as
+ * `@deprecated` references for the W6 cleanup window. They have no call
+ * site after the 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 W4 strategic-pass at
+ * `#1466 issuecomment-4362892782` for the loopback handoff lock.
  */
 /**
  * Minimal OpenClaw runtime surface passed to `auth.login`. Exposed as
@@ -67,8 +89,20 @@ interface AuthLoginContext {
  * 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
+ * Flow (W4 PR 3):
+ *   1. Run `loopbackHandoffFlow` against `apps/web` — a Stripe-style
+ *      browser-mediated runtime-key issuance that delivers the plaintext
+ *      `masons_rt_…` token to a one-shot loopback listener bound at
+ *      `127.0.0.1:0` with a fragment-nonce cross-origin discipline.
+ *   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 declare function login(ctx: AuthLoginContext): Promise<void>;

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"cli-setup.d.ts","sourceRoot":"","sources":["../src/cli-setup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AA2CH;;;;;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;AAw2BD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDhE"}

package/dist/cli-setup.js

@@ -1,5 +1,5 @@
 /**
- * CLI Login Path — OAuth 2.0 Device Authorization Grant (RFC 8628).
+ * CLI Login Path — Stripe-style browser-mediated loopback handoff.
  *
  * Implements `login()` hook for OpenClaw's 2026.4.x channel-plugin contract:
  *     api.registerChannel({ plugin: { ..., auth: { login } } })
@@ -9,29 +9,56 @@
  * `"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.)
+ * Flow (W4 PR 3 — `loopbackHandoffFlow`):
  *
- * 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.
+ *   1. Bind a one-shot HTTP listener on `127.0.0.1:0` (OS-assigned ephemeral
+ *      port). The listener serves a single `POST /handoff` plus the matching
+ *      CORS preflight, then closes.
+ *   2. Generate a 24-byte (32-char base64url) URL-safe random nonce. The
+ *      nonce travels in the URL fragment (`#nonce=…`), never the query
+ *      string — fragments do not reach `apps/web` access logs nor referer
+ *      headers (Alt W4-B2 lock).
+ *   3. Open the user's browser to the handoff URL (no-handle path uses
+ *      `${idpBaseUrl}/console/handoff?port=<port>#nonce=<nonce>`; with
+ *      `--handle` the per-handle deep-link variant is the entry).
+ *   4. The user authenticates against Better Auth on `apps/web`, picks (or
+ *      creates) an agent, and the page POSTs `{token, agent, key, nonce}`
+ *      to the listener. The listener verifies the body's `nonce` matches
+ *      the value it placed in the fragment, accepts the token, and closes.
+ *   5. Persist `{connectorUrl, token}` to `openclaw.json` via
+ *      `writeCredentials()`. `connectorUrl` is derived from `apiHost`
+ *      (`wss://<apiHost>/gateway`) for cloud / preview deployments; self-
+ *      hosted users keep an explicit `connectorUrl` in their `openclaw.json`
+ *      and the legacy value is preserved across the handoff (see
+ *      `loadExistingConnectorUrl()`).
  *
- * See #1264 for the design rationale (single-driver Node semantic — re-running
- * this flow rotates the api_key and evicts any previously-connected Runtime).
+ * Why move off device flow:
+ *
+ *   - One step shorter (no `user_code` to type into the browser).
+ *   - No periodic IdP polling (was 5s default, 5+s on `slow_down`).
+ *   - Browser remains fully authenticated across login and key issuance —
+ *     same Better Auth session is reused, so the user never re-types their
+ *     password mid-flow.
+ *   - The runtime API key carrier (`masons_rt_…`) replaces the legacy
+ *     connector-minted `sk-…` carrier; W4 PR 1 substrate plus the connector
+ *     mirror wiring earlier in this PR make both carriers verifiable through
+ *     plugin v0.5.13's life until the W6 cleanup retires the legacy path.
+ *
+ * The legacy device-flow helpers (`deviceCodeFlow`, `pollUntilAuthorized`,
+ * `agentSetup`, `createAgentLoop`) remain in this file as
+ * `@deprecated` references for the W6 cleanup window. They have no call
+ * site after the 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 W4 strategic-pass at
+ * `#1466 issuecomment-4362892782` for the loopback handoff lock.
  */
+import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { createServer, } from "node:http";
+import { homedir } from "node:os";
+import { join } from "node:path";
 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";
@@ -80,6 +107,345 @@ const CREATE_NEW_OPTION = "Create new agent";
 // 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}$/;
+/**
+ * Path under the loopback origin where `apps/web` POSTs the handoff payload.
+ * The listener accepts a CORS preflight on the same path. Pinning to a
+ * single path lets the listener reject any other request URL — defense in
+ * depth against a malicious local process binding the same port between
+ * the listener `listen()` and the browser POST.
+ */
+const HANDOFF_PATH = "/handoff";
+/**
+ * Hard cap on how long the listener waits for the browser POST. Long
+ * enough for the user to walk through sign-in + agent picker + handoff,
+ * short enough that a wedged listener doesn't sit on a port forever.
+ */
+const HANDOFF_TIMEOUT_MS = 5 * 60 * 1000;
+/** Bytes of entropy in the one-time fragment nonce. */
+const HANDOFF_NONCE_BYTES = 24;
+/**
+ * Run the Stripe-style loopback handoff. Returns the runtime API key
+ * + the agent identity the browser issued it for. The listener stops
+ * after a single successful POST; subsequent reuse of the URL is
+ * rejected.
+ *
+ * `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
+ * uses the per-handle deep-link entry; otherwise it falls back to the
+ * picker. Anything that isn't a handle prints a warning and falls
+ * through to the picker.
+ */
+async function loopbackHandoffFlow(idpBaseUrl, runtime, channelInput) {
+    const nonce = randomBytes(HANDOFF_NONCE_BYTES).toString("base64url");
+    // Bind the listener BEFORE printing the URL — the URL must carry the
+    // OS-assigned port and the listener must be ready to accept the POST
+    // before the user has any chance of opening the link.
+    const { server, port } = await bindLoopbackListener();
+    // The Promise we hand the inner request handler — resolved on a
+    // valid POST. The reject path is owned by the timeout race below
+    // (`Promise.race`); the request handler never produces a "fatal"
+    // error worth rejecting the outer promise — invalid bodies / wrong
+    // nonces / duplicate posts respond 4xx and let the listener keep
+    // running until the timeout or a valid POST wins.
+    let resolveResult = null;
+    const handoffPromise = new Promise((res) => {
+        resolveResult = res;
+    });
+    const browserOriginAllowList = computeAllowedBrowserOrigins(idpBaseUrl);
+    let dispatched = false;
+    server.on("request", (req, res) => {
+        // Two distinct security boundaries are layered on this listener and
+        // it's worth keeping them straight:
+        //
+        //   - The browser-origin allow-list (`computeAllowedBrowserOrigins`
+        //     + ACAO echo) closes the cross-origin browser-scrape surface
+        //     where a malicious page in the user's already-authenticated
+        //     browser tries to read the listener's response. ACAO is what
+        //     stops the browser from delivering the response to a non-
+        //     apps/web origin.
+        //   - The fragment nonce closes the local-process-race surface
+        //     where another process on the same machine binds the same
+        //     port between `server.listen()` and the browser POST. A
+        //     malicious local process can fake any `Origin` header at
+        //     will, but it cannot guess the 24-byte URL-fragment nonce
+        //     the listener generated.
+        //
+        // CORS preflight (`OPTIONS /handoff`) is browser-only — non-browser
+        // local processes do not preflight. We answer 204 with ACAO pinned
+        // to the request's origin if it is in the allow-list; otherwise
+        // 403 with no headers (browser blocks the subsequent POST).
+        const origin = req.headers.origin ?? "";
+        if (req.method === "OPTIONS" && req.url === HANDOFF_PATH) {
+            if (browserOriginAllowList.has(origin)) {
+                res.writeHead(204, {
+                    "Access-Control-Allow-Origin": origin,
+                    "Access-Control-Allow-Methods": "POST, OPTIONS",
+                    "Access-Control-Allow-Headers": "content-type",
+                    "Access-Control-Max-Age": "60",
+                });
+            }
+            else {
+                res.writeHead(403);
+            }
+            res.end();
+            return;
+        }
+        if (req.method !== "POST" || req.url !== HANDOFF_PATH) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        if (!browserOriginAllowList.has(origin)) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        // Read the POST body with a hard cap. The expected payload is
+        // ~1 KB; reject anything larger as protection against a wedged
+        // attacker streaming bytes into the listener.
+        const MAX_BODY = 64 * 1024;
+        const chunks = [];
+        let total = 0;
+        let aborted = false;
+        req.on("data", (chunk) => {
+            if (aborted)
+                return;
+            total += chunk.length;
+            if (total > MAX_BODY) {
+                aborted = true;
+                // Origin already validated against the allow-list above; ACAO
+                // is therefore safe to echo and lets the browser surface the
+                // 413 status to the page (rather than an opaque CORS error).
+                res.writeHead(413, { "Access-Control-Allow-Origin": origin });
+                res.end();
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (aborted)
+                return;
+            let parsed = null;
+            try {
+                parsed = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+            }
+            catch {
+                res.writeHead(400, { "Access-Control-Allow-Origin": origin });
+                res.end();
+                return;
+            }
+            if (!parsed ||
+                typeof parsed.token !== "string" ||
+                typeof parsed.nonce !== "string" ||
+                !parsed.agent ||
+                typeof parsed.agent.agentId !== "string" ||
+                typeof parsed.agent.handle !== "string") {
+                res.writeHead(400, { "Access-Control-Allow-Origin": origin });
+                res.end();
+                return;
+            }
+            if (parsed.nonce !== nonce) {
+                // Wrong nonce — possibly a stale browser tab from an earlier
+                // login attempt that lost the race for the port, or a
+                // malicious local process. Reject without revealing why.
+                res.writeHead(403, { "Access-Control-Allow-Origin": origin });
+                res.end();
+                return;
+            }
+            if (dispatched) {
+                // The listener is one-shot. Any subsequent POST after the
+                // first valid one is suspect — the browser succeeded once
+                // already; nothing else should be hitting this URL.
+                res.writeHead(409, { "Access-Control-Allow-Origin": origin });
+                res.end();
+                return;
+            }
+            dispatched = true;
+            res.writeHead(200, { "Access-Control-Allow-Origin": origin });
+            res.end();
+            resolveResult?.({
+                token: parsed.token,
+                agent: {
+                    agentId: parsed.agent.agentId,
+                    handle: parsed.agent.handle,
+                    name: typeof parsed.agent.name === "string"
+                        ? parsed.agent.name
+                        : parsed.agent.handle,
+                },
+            });
+        });
+        req.on("error", () => {
+            if (!dispatched) {
+                // Connection-level error before we got a body. Log nothing —
+                // half-formed requests are noisy and usually irrelevant.
+            }
+        });
+    });
+    // The handoff URL the user (or `open`/`xdg-open`) navigates to. The
+    // nonce sits in the fragment so it never lands in apps/web access
+    // logs nor referer headers.
+    const handle = parseHandleFromInput(channelInput);
+    const baseUrl = handle
+        ? `${idpBaseUrl}/console/agents/${encodeURIComponent(handle)}/runtime-keys/handoff`
+        : `${idpBaseUrl}/console/handoff`;
+    const url = `${baseUrl}?port=${port}#nonce=${nonce}`;
+    runtime.writeStdout([
+        "",
+        "Open this link in your browser to finish the handoff:",
+        `  ${url}`,
+        "",
+        "Waiting for the browser to deliver the runtime key…",
+        "",
+    ].join("\n"));
+    // Best-effort spawn `open` / `xdg-open` / `start` so the browser
+    // pops automatically. Failure is non-fatal — the printed URL is the
+    // documented fallback.
+    void tryOpenBrowser(url, runtime);
+    // Race the listener against the timeout. Unwrap whichever wins.
+    const timeoutPromise = new Promise((_, rej) => {
+        setTimeout(() => {
+            rej(new DeviceFlowError("Loopback handoff timed out without receiving the runtime key. " +
+                "Re-run setup; if your browser cannot reach 127.0.0.1, copy the " +
+                "URL into a browser on the same machine."));
+        }, HANDOFF_TIMEOUT_MS).unref();
+    });
+    try {
+        return await Promise.race([handoffPromise, timeoutPromise]);
+    }
+    finally {
+        // Closing the listener after the first valid POST mirrors the
+        // "one-shot accept" discipline. Outstanding sockets (e.g., a
+        // preflight that arrived after the dispatch) are dropped on close.
+        server.close();
+    }
+}
+async function bindLoopbackListener() {
+    return await new Promise((resolve, reject) => {
+        const server = createServer();
+        server.on("error", reject);
+        // `127.0.0.1` (not `0.0.0.0`) — only the local machine can reach
+        // the listener. Browsers permit cross-origin fetch from HTTPS to
+        // 127.0.0.1 because it is a "potentially trustworthy origin"
+        // (W3C secure-contexts spec).
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                reject(new Error("Failed to bind loopback listener — no address"));
+                return;
+            }
+            resolve({ server, port: addr.port });
+        });
+    });
+}
+/**
+ * Compute the allowed browser origins for the cross-origin POST. The
+ * allow-list pins to the exact apps/web origin (scheme + host + port)
+ * so a local malicious process bound to a different origin cannot
+ * scrape the listener even if it happens to discover the port.
+ *
+ * Both the bare `idpBaseUrl` and (for development) `http://localhost:3007`
+ * are allowed when `idpBaseUrl` resolves to a localhost hostname so the
+ * `pnpm dev` workflow works without flag-flipping.
+ */
+function computeAllowedBrowserOrigins(idpBaseUrl) {
+    const origins = new Set();
+    try {
+        const url = new URL(idpBaseUrl);
+        origins.add(url.origin);
+        if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
+            origins.add("http://localhost:3007");
+            origins.add("http://127.0.0.1:3007");
+        }
+    }
+    catch {
+        // Malformed idpBaseUrl — fall through with an empty allow-list.
+        // Every browser POST will be 403'd; the user sees a timeout.
+    }
+    return origins;
+}
+/**
+ * Best-effort browser launch. Returns immediately; failures are
+ * surfaced as a quiet log rather than a thrown error — the user has
+ * the printed URL as a documented fallback.
+ */
+async function tryOpenBrowser(url, runtime) {
+    const { spawn } = await import("node:child_process");
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.on("error", (err) => {
+            runtime.log(`(could not auto-open browser: ${err.message} — copy the link above)`);
+        });
+        child.unref();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "unknown error";
+        runtime.log(`(could not auto-open browser: ${message} — copy the link above)`);
+    }
+}
+/**
+ * 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;
+    const trimmed = input.trim().toLowerCase();
+    if (!HANDLE_REGEX.test(trimmed))
+        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 loopback flow does not learn
+ * it from `apps/api` (issuance is decoupled from connector topology),
+ * but we don't want to clobber a user-set value.
+ *
+ * Returns `undefined` when the file is absent, malformed, or doesn't
+ * contain a connectorUrl. Caller falls back to `deriveCloudConnectorUrl`.
+ */
+async function loadExistingConnectorUrl() {
+    const home = process.env.OPENCLAW_HOME || join(homedir(), ".openclaw");
+    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
+ * loopback 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 {
@@ -95,7 +461,14 @@ 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 `loopbackHandoffFlow`. No call
+ * site after the W4 PR 3 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);
@@ -144,6 +517,8 @@ async function initDeviceCode(idpBaseUrl) {
     }
     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 (;;) {
@@ -199,6 +574,8 @@ function sleep(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
@@ -256,6 +633,8 @@ async function agentSetup(apiHost, accessToken, prompter) {
     // 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):");
@@ -298,7 +677,12 @@ async function createAgentLoop(platformCfg, accessToken, prompter) {
  * 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 loopback handoff uses `clack` indirectly
+ * via the spinner-style stdout writes in `loopbackHandoffFlow`.
  */
+// biome-ignore lint/correctness/noUnusedVariables: retained for the @deprecated device-flow helpers
 function createClackPrompter() {
     const abortOnCancel = (result) => {
         if (isCancel(result)) {
@@ -350,8 +734,20 @@ function createClackPrompter() {
  * 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
+ * Flow (W4 PR 3):
+ *   1. Run `loopbackHandoffFlow` against `apps/web` — a Stripe-style
+ *      browser-mediated runtime-key issuance that delivers the plaintext
+ *      `masons_rt_…` token to a one-shot loopback listener bound at
+ *      `127.0.0.1:0` with a fragment-nonce cross-origin discipline.
+ *   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) {
@@ -361,37 +757,37 @@ export async function login(ctx) {
     const idpBaseUrl = typeof ctx.cfg.idpBaseUrl === "string"
         ? ctx.cfg.idpBaseUrl
         : DEFAULT_IDP_BASE_URL;
-    const prompter = createClackPrompter();
-    let creds;
+    let handoff;
     try {
-        const accessToken = await deviceCodeFlow(idpBaseUrl, prompter);
-        creds = await agentSetup(apiHost, accessToken, prompter);
+        handoff = await loopbackHandoffFlow(idpBaseUrl, ctx.runtime, ctx.channelInput);
     }
     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.
+            // User pressed Ctrl+C — clack already emitted the cancel UI.
             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.
+            // Loopback 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.)
             ctx.runtime.error(err.message);
             return;
         }
         if (err instanceof PlatformApiError) {
-            ctx.runtime.error(`Onboard failed (HTTP ${err.status} ${err.code}): ${err.message}`);
+            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;
     }
-    // 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}`);
+    // `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);
+    await writeCredentials({ connectorUrl, token: handoff.token }, apiHost, idpBaseUrl);
+    ctx.runtime.log(`✓ Connected as @${handoff.agent.handle}`);
 }

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export declare const PLUGIN_VERSION = "0.5.12";
+export declare const PLUGIN_VERSION = "0.5.13";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export const PLUGIN_VERSION = "0.5.12";
+export const PLUGIN_VERSION = "0.5.13";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "MASONS plugin for OpenClaw — connect your agent to the agent network",
   "license": "MIT",
   "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",

package/dist/session-lifecycle.d.ts

@@ -1,89 +0,0 @@
-/**
- * Session Lifecycle — manages MSTP session state per contact.
- *
- * State machine: idle -> creating -> active -> recreating -> failed.
- * Internal key: MSTP address (not handle) — supports same handle on different Connectors.
- *
- * Responsibilities:
- * - Maps MSTP address to session state (sessionId, status, pending promise)
- * - Auto-creates sessions on demand via ensureSession()
- * - Deduplicates concurrent creates (second caller awaits first's promise)
- * - Registers inbound sessions from remote agents
- * - Invalidates all sessions on transport disconnect
- * - Subscribes to ConnectorClient events: session_created, session_error, session_ended, disconnected
- *
- * @see docs/openclaw/session-abstraction-system-design.md §6.1
- */
-import type { ConnectorClient } from "./connector-client.js";
-export type SessionStatus = "idle" | "creating" | "active" | "recreating" | "failed";
-export interface SessionState {
-    status: SessionStatus;
-    sessionId: string | null;
-    pendingRequestId: string | null;
-    retryCount: number;
-    /** Promise that resolves when session creation completes. Used for dedup. */
-    createPromise: Promise<string> | null;
-    /** Resolve function for the create promise. */
-    createResolve: ((sessionId: string) => void) | null;
-    /** Reject function for the create promise. */
-    createReject: ((err: Error) => void) | null;
-}
-export declare class SessionLifecycle {
-    private readonly client;
-    /** Primary map: MSTP address -> session state */
-    private readonly sessions;
-    /** Reverse index: sessionId -> MSTP address */
-    private readonly sessionToAddress;
-    /** Configurable timeout for tests */
-    private timeoutMs;
-    constructor(client: ConnectorClient);
-    /**
-     * Ensure an active session exists for the given address.
-     * Returns the sessionId. Creates a new session if none exists.
-     * Concurrent callers get the same promise (dedup).
-     */
-    ensureSession(address: string): Promise<string>;
-    /**
-     * Get the active sessionId for an address, or null.
-     */
-    getSession(address: string): string | null;
-    /**
-     * Close the session for an address.
-     */
-    closeSession(address: string, reason?: string): void;
-    /**
-     * Register an inbound session (remote initiated).
-     */
-    registerInbound(sessionId: string, address: string): void;
-    /**
-     * Invalidate all sessions. Called on transport disconnect.
-     * Conversations are preserved but sessions are cleared.
-     */
-    invalidateAll(): void;
-    /**
-     * Reverse lookup: sessionId -> MSTP address.
-     */
-    getAddressBySessionId(sessionId: string): string | undefined;
-    /**
-     * Get all session entries (for listing conversations).
-     */
-    listSessions(): Array<{
-        address: string;
-        status: SessionStatus;
-        sessionId: string | null;
-    }>;
-    /**
-     * Remove a session entry entirely (for endConversation).
-     */
-    removeSession(address: string): void;
-    /** @internal Override timeout for tests. */
-    _setTimeoutForTesting(ms: number): void;
-    /** @internal Reset for test isolation. */
-    _resetForTesting(): void;
-    private subscribe;
-    private createNewSession;
-    private handleSessionCreated;
-    private handleSessionEnded;
-    private handleSessionError;
-}
-//# sourceMappingURL=session-lifecycle.d.ts.map

package/dist/session-lifecycle.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"session-lifecycle.d.ts","sourceRoot":"","sources":["../src/session-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAQ7D,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,QAAQ,CAAC;AAEb,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACtC,+CAA+C;IAC/C,aAAa,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACpD,8CAA8C;IAC9C,YAAY,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7C;AAaD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAE9D,qCAAqC;IACrC,OAAO,CAAC,SAAS,CAA6B;gBAElC,MAAM,EAAE,eAAe;IASnC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB/C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQ1C;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBpD;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAqBzD;;;OAGG;IACH,aAAa,IAAI,IAAI;IAqBrB;;OAEG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5D;;OAEG;IACH,YAAY,IAAI,KAAK,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,aAAa,CAAC;QACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC;IAgBF;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAcpC,4CAA4C;IAC5C,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIvC,0CAA0C;IAC1C,gBAAgB,IAAI,IAAI;IAmBxB,OAAO,CAAC,SAAS;IAsBjB,OAAO,CAAC,gBAAgB;IA+GxB,OAAO,CAAC,oBAAoB;IAuC5B,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,kBAAkB;CA0B3B"}

package/dist/session-lifecycle.js

@@ -1,348 +0,0 @@
-/**
- * Session Lifecycle — manages MSTP session state per contact.
- *
- * State machine: idle -> creating -> active -> recreating -> failed.
- * Internal key: MSTP address (not handle) — supports same handle on different Connectors.
- *
- * Responsibilities:
- * - Maps MSTP address to session state (sessionId, status, pending promise)
- * - Auto-creates sessions on demand via ensureSession()
- * - Deduplicates concurrent creates (second caller awaits first's promise)
- * - Registers inbound sessions from remote agents
- * - Invalidates all sessions on transport disconnect
- * - Subscribes to ConnectorClient events: session_created, session_error, session_ended, disconnected
- *
- * @see docs/openclaw/session-abstraction-system-design.md §6.1
- */
-import createDebug from "debug";
-const dbg = createDebug("agent-network:session-lifecycle");
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const SESSION_CREATE_TIMEOUT_MS = 15_000;
-const MAX_RETRY_COUNT = 1;
-// ---------------------------------------------------------------------------
-// SessionLifecycle
-// ---------------------------------------------------------------------------
-export class SessionLifecycle {
-    client;
-    /** Primary map: MSTP address -> session state */
-    sessions = new Map();
-    /** Reverse index: sessionId -> MSTP address */
-    sessionToAddress = new Map();
-    /** Configurable timeout for tests */
-    timeoutMs = SESSION_CREATE_TIMEOUT_MS;
-    constructor(client) {
-        this.client = client;
-        this.subscribe();
-    }
-    // -------------------------------------------------------------------------
-    // Public API
-    // -------------------------------------------------------------------------
-    /**
-     * Ensure an active session exists for the given address.
-     * Returns the sessionId. Creates a new session if none exists.
-     * Concurrent callers get the same promise (dedup).
-     */
-    ensureSession(address) {
-        const state = this.sessions.get(address);
-        // Active session — return immediately
-        if (state?.status === "active" && state.sessionId) {
-            return Promise.resolve(state.sessionId);
-        }
-        // Creating/recreating — dedup: return existing promise
-        if ((state?.status === "creating" || state?.status === "recreating") &&
-            state.createPromise) {
-            return state.createPromise;
-        }
-        // Idle, failed, or no state — create new session
-        return this.createNewSession(address, state?.retryCount ?? 0);
-    }
-    /**
-     * Get the active sessionId for an address, or null.
-     */
-    getSession(address) {
-        const state = this.sessions.get(address);
-        if (state?.status === "active" && state.sessionId) {
-            return state.sessionId;
-        }
-        return null;
-    }
-    /**
-     * Close the session for an address.
-     */
-    closeSession(address, reason) {
-        const state = this.sessions.get(address);
-        if (!state)
-            return;
-        if (state.sessionId) {
-            this.client.endSession(state.sessionId, reason);
-            this.sessionToAddress.delete(state.sessionId);
-        }
-        // Reject any pending create promise
-        if (state.createReject) {
-            state.createReject(new Error("Session closed by caller"));
-            state.createResolve = null;
-            state.createReject = null;
-            state.createPromise = null;
-        }
-        this.sessions.delete(address);
-        dbg("closeSession address=%s", address);
-    }
-    /**
-     * Register an inbound session (remote initiated).
-     */
-    registerInbound(sessionId, address) {
-        // If there's an existing session for this address, clean up
-        const existing = this.sessions.get(address);
-        if (existing?.sessionId && existing.sessionId !== sessionId) {
-            this.sessionToAddress.delete(existing.sessionId);
-        }
-        const state = {
-            status: "active",
-            sessionId,
-            pendingRequestId: null,
-            retryCount: 0,
-            createPromise: null,
-            createResolve: null,
-            createReject: null,
-        };
-        this.sessions.set(address, state);
-        this.sessionToAddress.set(sessionId, address);
-        dbg("registerInbound sessionId=%s address=%s", sessionId, address);
-    }
-    /**
-     * Invalidate all sessions. Called on transport disconnect.
-     * Conversations are preserved but sessions are cleared.
-     */
-    invalidateAll() {
-        const count = this.sessions.size;
-        for (const [address, state] of this.sessions) {
-            // Reject pending creates
-            if (state.createReject) {
-                state.createReject(new Error("Transport disconnected"));
-                state.createResolve = null;
-                state.createReject = null;
-                state.createPromise = null;
-            }
-            // Reset to idle — next send() will auto-create
-            state.status = "idle";
-            state.sessionId = null;
-            state.pendingRequestId = null;
-            state.retryCount = 0;
-            this.sessions.set(address, state);
-        }
-        this.sessionToAddress.clear();
-        dbg("invalidateAll cleared %d sessions", count);
-    }
-    /**
-     * Reverse lookup: sessionId -> MSTP address.
-     */
-    getAddressBySessionId(sessionId) {
-        return this.sessionToAddress.get(sessionId);
-    }
-    /**
-     * Get all session entries (for listing conversations).
-     */
-    listSessions() {
-        const entries = [];
-        for (const [address, state] of this.sessions) {
-            entries.push({
-                address,
-                status: state.status,
-                sessionId: state.sessionId,
-            });
-        }
-        return entries;
-    }
-    /**
-     * Remove a session entry entirely (for endConversation).
-     */
-    removeSession(address) {
-        const state = this.sessions.get(address);
-        if (state?.sessionId) {
-            this.sessionToAddress.delete(state.sessionId);
-        }
-        if (state?.createReject) {
-            state.createReject(new Error("Session removed"));
-            state.createResolve = null;
-            state.createReject = null;
-            state.createPromise = null;
-        }
-        this.sessions.delete(address);
-    }
-    /** @internal Override timeout for tests. */
-    _setTimeoutForTesting(ms) {
-        this.timeoutMs = ms;
-    }
-    /** @internal Reset for test isolation. */
-    _resetForTesting() {
-        // Reject pending creates silently
-        for (const state of this.sessions.values()) {
-            if (state.createReject) {
-                state.createReject(new Error("Reset for testing"));
-                state.createResolve = null;
-                state.createReject = null;
-                state.createPromise = null;
-            }
-        }
-        this.sessions.clear();
-        this.sessionToAddress.clear();
-        this.timeoutMs = SESSION_CREATE_TIMEOUT_MS;
-    }
-    // -------------------------------------------------------------------------
-    // Private
-    // -------------------------------------------------------------------------
-    subscribe() {
-        this.client.on("session_created", (event) => {
-            this.handleSessionCreated(event.sessionId, event.requestId, event.direction);
-        });
-        this.client.on("session_error", (sessionId, message) => {
-            this.handleSessionError(sessionId, message);
-        });
-        this.client.on("session_ended", (event) => {
-            this.handleSessionEnded(event.sessionId);
-        });
-        this.client.on("disconnected", () => {
-            this.invalidateAll();
-        });
-    }
-    createNewSession(address, previousRetryCount) {
-        const status = previousRetryCount > 0 ? "recreating" : "creating";
-        let createResolve = null;
-        let createReject = null;
-        const createPromise = new Promise((resolve, reject) => {
-            createResolve = resolve;
-            createReject = reject;
-        });
-        const { requestId, sent } = this.client.createSession(address);
-        if (!sent) {
-            const state = {
-                status: "failed",
-                sessionId: null,
-                pendingRequestId: null,
-                retryCount: previousRetryCount,
-                createPromise: null,
-                createResolve: null,
-                createReject: null,
-            };
-            this.sessions.set(address, state);
-            return Promise.reject(new Error("Failed to create session: transport unavailable"));
-        }
-        const state = {
-            status,
-            sessionId: null,
-            pendingRequestId: requestId,
-            retryCount: previousRetryCount,
-            createPromise,
-            createResolve,
-            createReject,
-        };
-        this.sessions.set(address, state);
-        // Timeout
-        const timer = setTimeout(() => {
-            const current = this.sessions.get(address);
-            if (current &&
-                current.pendingRequestId === requestId &&
-                (current.status === "creating" || current.status === "recreating")) {
-                dbg("session create timeout address=%s requestId=%s", address, requestId);
-                // Can we retry?
-                if (current.retryCount < MAX_RETRY_COUNT) {
-                    // Move to failed, then retry
-                    current.status = "failed";
-                    current.retryCount++;
-                    current.pendingRequestId = null;
-                    const retryResolve = current.createResolve;
-                    const retryReject = current.createReject;
-                    current.createPromise = null;
-                    current.createResolve = null;
-                    current.createReject = null;
-                    this.sessions.set(address, current);
-                    // Retry: create a new session, pipe result to original promise
-                    this.createNewSession(address, current.retryCount)
-                        .then((sessionId) => retryResolve?.(sessionId))
-                        .catch((err) => retryReject?.(err));
-                }
-                else {
-                    // Max retries exhausted
-                    current.status = "idle";
-                    current.pendingRequestId = null;
-                    current.retryCount = 0;
-                    if (current.createReject) {
-                        current.createReject(new Error("Session creation timed out. The remote agent may be unavailable."));
-                    }
-                    current.createPromise = null;
-                    current.createResolve = null;
-                    current.createReject = null;
-                    this.sessions.set(address, current);
-                }
-            }
-        }, this.timeoutMs);
-        // Attach cleanup to the promise to clear the timer if resolved early
-        createPromise
-            .then(() => clearTimeout(timer))
-            .catch(() => clearTimeout(timer));
-        dbg("createNewSession address=%s requestId=%s status=%s retry=%d", address, requestId, status, previousRetryCount);
-        return createPromise;
-    }
-    handleSessionCreated(sessionId, requestId, direction) {
-        // Outbound: match by requestId
-        if (direction === "outbound" && requestId) {
-            for (const [address, state] of this.sessions) {
-                if (state.pendingRequestId === requestId &&
-                    (state.status === "creating" || state.status === "recreating")) {
-                    state.status = "active";
-                    state.sessionId = sessionId;
-                    state.pendingRequestId = null;
-                    this.sessionToAddress.set(sessionId, address);
-                    if (state.createResolve) {
-                        state.createResolve(sessionId);
-                    }
-                    state.createPromise = null;
-                    state.createResolve = null;
-                    state.createReject = null;
-                    dbg("session created (outbound) address=%s sessionId=%s", address, sessionId);
-                    return;
-                }
-            }
-        }
-        // Inbound sessions are registered externally via registerInbound()
-        // from the channel adapter (which has the metadata to derive the address).
-        // We don't handle inbound SESSION_CREATED here.
-    }
-    handleSessionEnded(sessionId) {
-        const address = this.sessionToAddress.get(sessionId);
-        if (!address)
-            return;
-        const state = this.sessions.get(address);
-        if (!state)
-            return;
-        // Only clear if this session is the current one
-        if (state.sessionId === sessionId) {
-            state.status = "idle";
-            state.sessionId = null;
-            dbg("session ended address=%s sessionId=%s", address, sessionId);
-        }
-        this.sessionToAddress.delete(sessionId);
-    }
-    handleSessionError(sessionId, message) {
-        const address = this.sessionToAddress.get(sessionId);
-        if (!address)
-            return;
-        const state = this.sessions.get(address);
-        if (!state)
-            return;
-        dbg("session error address=%s sessionId=%s message=%s", address, sessionId, message);
-        // Session error on active session — mark for auto-recreate on next send().
-        // Reset retryCount to 0: this is a new failure context (transport error),
-        // not a continuation of a creation timeout. The next ensureSession() gets
-        // a fresh retry budget.
-        if (state.status === "active") {
-            this.sessionToAddress.delete(sessionId);
-            state.status = "idle";
-            state.sessionId = null;
-            state.retryCount = 0;
-            dbg("auto-recreate queued address=%s", address);
-        }
-    }
-}