Onboarding: fix webchat URL loopback and canonical session

src/commands/onboard-helpers.e2e.test.ts

@@ -1,9 +1,11 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
+  buildWebchatUrl,
   normalizeGatewayTokenInput,
   openUrl,
   resolveBrowserOpenCommand,
   resolveControlUiLinks,
+  resolveLocalBrowserControlUiLinks,
   validateGatewayPasswordInput,
 } from "./onboard-helpers.js";
 
@@ -107,6 +109,35 @@ describe("resolveControlUiLinks", () => {
     expect(links.httpUrl).toBe("http://127.0.0.1:18789/");
     expect(links.wsUrl).toBe("ws://127.0.0.1:18789");
   });
+
+  it("coerces lan bind to loopback for local browser links", () => {
+    const links = resolveLocalBrowserControlUiLinks({
+      port: 18789,
+      bind: "lan",
+    });
+    expect(links.httpUrl).toBe("http://127.0.0.1:18789/");
+    expect(links.wsUrl).toBe("ws://127.0.0.1:18789");
+  });
+});
+
+describe("buildWebchatUrl", () => {
+  it("encodes canonical session key exactly once", () => {
+    const url = buildWebchatUrl({
+      httpUrl: "http://127.0.0.1:18789/",
+      sessionKey: "agent:main:main",
+    });
+    expect(url).toBe("http://127.0.0.1:18789/chat?session=agent%3Amain%3Amain");
+  });
+
+  it("preserves base path and appends token in fragment", () => {
+    const url = buildWebchatUrl({
+      httpUrl: "http://127.0.0.1:18789/ui/",
+      sessionKey: "agent:main:main",
+      token: "abc 123",
+    });
+    expect(url).toBe("http://127.0.0.1:18789/ui/chat?session=agent%3Amain%3Amain#token=abc%20123");
+    expect(url).not.toContain("%2520");
+  });
 });
 
 describe("normalizeGatewayTokenInput", () => {

src/commands/onboard-helpers.ts

@@ -8,7 +8,7 @@ import type { RuntimeEnv } from "../runtime.js";
 import type { NodeManagerChoice, OnboardMode, ResetScope } from "./onboard-types.js";
 import { DEFAULT_AGENT_WORKSPACE_DIR, ensureAgentWorkspace } from "../agents/workspace.js";
 import { CONFIG_PATH } from "../config/config.js";
-import { resolveSessionTranscriptsDirForAgent } from "../config/sessions.js";
+import { resolveMainSessionKey, resolveSessionTranscriptsDirForAgent } from "../config/sessions.js";
 import { callGateway } from "../gateway/call.js";
 import { normalizeControlUiBasePath } from "../gateway/control-ui-shared.js";
 import { pickPrimaryLanIPv4, isValidIPv4 } from "../gateway/net.js";
@@ -454,12 +454,17 @@ function summarizeError(err: unknown): string {
 
 export const DEFAULT_WORKSPACE = DEFAULT_AGENT_WORKSPACE_DIR;
 
-export function resolveControlUiLinks(params: {
+type ControlUiLinksParams = {
   port: number;
   bind?: "auto" | "lan" | "loopback" | "custom" | "tailnet";
   customBindHost?: string;
   basePath?: string;
-}): { httpUrl: string; wsUrl: string } {
+};
+
+export function resolveControlUiLinks(params: ControlUiLinksParams): {
+  httpUrl: string;
+  wsUrl: string;
+} {
   const port = params.port;
   const bind = params.bind ?? "loopback";
   const customBindHost = params.customBindHost?.trim();
@@ -484,3 +489,39 @@ export function resolveControlUiLinks(params: {
     wsUrl: `ws://${host}:${port}${wsPath}`,
   };
 }
+
+export function resolveLocalBrowserControlUiLinks(params: ControlUiLinksParams): {
+  httpUrl: string;
+  wsUrl: string;
+} {
+  const bind = params.bind === "lan" ? "loopback" : params.bind;
+  return resolveControlUiLinks({
+    ...params,
+    bind,
+  });
+}
+
+export function resolveCanonicalMainSessionKey(cfg: OpenClawConfig): string {
+  return resolveMainSessionKey(cfg);
+}
+
+export function buildWebchatUrl(params: {
+  httpUrl: string;
+  sessionKey: string;
+  token?: string;
+}): string {
+  const base = new URL(params.httpUrl);
+  if (!base.pathname.endsWith("/")) {
+    base.pathname = `${base.pathname}/`;
+  }
+
+  const chatUrl = new URL("chat", base);
+  chatUrl.searchParams.set("session", params.sessionKey.trim());
+
+  const token = params.token?.trim();
+  if (token) {
+    chatUrl.hash = `token=${encodeURIComponent(token)}`;
+  }
+
+  return chatUrl.toString();
+}