@abot-ai/runtime 1.0.0

package/dist/src/web-ui/local-runtime-backend.js

@@ -0,0 +1,60 @@
+import { LocalRuntimeApiRouter } from "./local-runtime/api-router.js";
+import { LocalRuntimeControlRoutes } from "./local-runtime/control-routes.js";
+import { RuntimeEnvironmentRegistry } from "./local-runtime/environment-registry.js";
+import { sendJson } from "./local-runtime/http.js";
+import { LocalRealtimeController } from "./local-runtime/realtime-controller.js";
+import { RealtimeClientHub } from "./local-runtime/realtime-hub.js";
+import { LocalRequestExecution } from "./local-runtime/request-execution.js";
+/** Stable server-facing facade for the direct Runtime Web UI backend. */
+export class LocalRuntimeWebBackend {
+    environments;
+    api;
+    realtime;
+    controls;
+    constructor(options) {
+        this.environments = new RuntimeEnvironmentRegistry(options);
+        const clients = new RealtimeClientHub();
+        const requests = new LocalRequestExecution(clients);
+        this.api = new LocalRuntimeApiRouter(options, this.environments, requests);
+        this.realtime = new LocalRealtimeController(options, this.environments, requests, clients);
+        this.controls = new LocalRuntimeControlRoutes(requests);
+    }
+    async handleHttp(req, res, pathname) {
+        try {
+            if (pathname === "/web-health" || pathname === "/web-api/health") {
+                this.controls.health(res);
+                return true;
+            }
+            if (pathname === "/web-agent-mode" ||
+                pathname === "/web-api/agent-mode") {
+                await this.controls.agentModeRoute(req, res);
+                return true;
+            }
+            if (pathname === "/assistant-host/assistant/status") {
+                this.controls.assistantStatus(res);
+                return true;
+            }
+            if (pathname === "/assistant-host/assistant/tick" ||
+                pathname === "/assistant-host/assistant/feedback") {
+                this.controls.assistantMutationFallback(res);
+                return true;
+            }
+            if (pathname.startsWith("/web-api/") || pathname === "/web-api") {
+                await this.api.handle(req, res);
+                return true;
+            }
+            return false;
+        }
+        catch (error) {
+            sendJson(res, 500, {
+                ok: false,
+                error: "local_runtime_backend_error",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return true;
+        }
+    }
+    handleRealtimeConnection(client) {
+        this.realtime.connect(client);
+    }
+}

package/dist/src/web-ui/runtime-service-auto-open.d.ts

@@ -0,0 +1,58 @@
+export type RuntimeServiceWebUiSettings = Readonly<{
+    enabled: boolean;
+    listenHost: string;
+    port: number;
+    browserUrl: string;
+    healthUrl: string;
+}>;
+export type ReadinessResult = Readonly<{
+    ready: boolean;
+    attempts: number;
+    lastError?: string;
+}>;
+export type AutoOpenResult = Readonly<{
+    status: "disabled";
+}> | Readonly<{
+    status: "opened";
+    url: string;
+    attempts: number;
+}> | Readonly<{
+    status: "not-ready" | "open-failed";
+    url: string;
+    attempts: number;
+    error: string;
+}>;
+type FetchResponse = Readonly<{
+    ok: boolean;
+    status: number;
+}>;
+type FetchLike = (input: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<FetchResponse>;
+type SpawnBrowser = (executable: string, args: readonly string[], env: NodeJS.ProcessEnv) => Promise<void>;
+export declare function resolveRuntimeServiceWebUiSettings(params: {
+    rootDir: string;
+    configPath?: string;
+    env?: NodeJS.ProcessEnv;
+}): RuntimeServiceWebUiSettings;
+export declare function waitForWebUiReady(healthUrl: string, options?: {
+    fetch?: FetchLike;
+    sleep?: (durationMs: number) => Promise<void>;
+    timeoutMs?: number;
+    intervalMs?: number;
+    requestTimeoutMs?: number;
+    now?: () => number;
+}): Promise<ReadinessResult>;
+export declare function resolveWslgBrowserEnvironment(env?: NodeJS.ProcessEnv, userId?: number): NodeJS.ProcessEnv;
+export declare function openWebUiInWslg(url: string, options?: {
+    env?: NodeJS.ProcessEnv;
+    exists?: (path: string) => boolean;
+    spawnBrowser?: SpawnBrowser;
+    userId?: number;
+}): Promise<void>;
+export declare function runRuntimeServiceWebUiAutoOpen(params: {
+    settings: RuntimeServiceWebUiSettings;
+    waitUntilReady?: typeof waitForWebUiReady;
+    openBrowser?: (url: string) => Promise<void>;
+}): Promise<AutoOpenResult>;
+export {};

package/dist/src/web-ui/runtime-service-auto-open.js

@@ -0,0 +1,167 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { inspectRuntimeConfigFileWithMeta } from "../runtime/config/loader.js";
+import { validateRuntimeWebUiConfig } from "../runtime/config/validation.js";
+import { resolveWebUiAddress } from "./web-ui-address.js";
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+const DEFAULT_READY_INTERVAL_MS = 250;
+const DEFAULT_REQUEST_TIMEOUT_MS = 2_000;
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function resolveRuntimeServiceWebUiSettings(params) {
+    const env = params.env ?? process.env;
+    const source = inspectRuntimeConfigFileWithMeta(params.rootDir, params.configPath ?? env.LLM_RUNTIME_CONFIG_FILE);
+    validateRuntimeWebUiConfig(source.config, source.path);
+    const config = source.config;
+    const webUi = isRecord(config.webUi) ? config.webUi : undefined;
+    const enabled = webUi?.openOnRuntimeServiceStart === true;
+    const address = resolveWebUiAddress(env);
+    return {
+        enabled,
+        listenHost: address.listenHost,
+        port: address.port,
+        browserUrl: address.browserUrl,
+        healthUrl: address.healthUrl,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export async function waitForWebUiReady(healthUrl, options = {}) {
+    const fetchHealth = options.fetch ?? fetch;
+    const sleep = options.sleep ??
+        ((durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs)));
+    const timeoutMs = Math.max(0, options.timeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+    const intervalMs = Math.max(1, options.intervalMs ?? DEFAULT_READY_INTERVAL_MS);
+    const requestTimeoutMs = Math.max(1, options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+    const now = options.now ?? Date.now;
+    const deadline = now() + timeoutMs;
+    let attempts = 0;
+    let lastError = "Web UI did not become ready";
+    while (attempts === 0 || now() < deadline) {
+        attempts += 1;
+        const controller = new AbortController();
+        const remainingMs = Math.max(1, deadline - now());
+        const requestBudgetMs = Math.min(requestTimeoutMs, remainingMs);
+        let timeout;
+        const requestDeadline = new Promise((_resolve, reject) => {
+            timeout = setTimeout(() => {
+                controller.abort();
+                reject(new Error("health request timed out"));
+            }, requestBudgetMs);
+        });
+        try {
+            const response = await Promise.race([
+                fetchHealth(healthUrl, { signal: controller.signal }),
+                requestDeadline,
+            ]);
+            if (response.ok) {
+                return { ready: true, attempts };
+            }
+            lastError = `health endpoint returned HTTP ${response.status}`;
+        }
+        catch (error) {
+            lastError = errorMessage(error);
+        }
+        finally {
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+        }
+        const remainingAfterAttemptMs = deadline - now();
+        if (remainingAfterAttemptMs <= 0)
+            break;
+        await sleep(Math.min(intervalMs, remainingAfterAttemptMs));
+    }
+    return { ready: false, attempts, lastError };
+}
+export function resolveWslgBrowserEnvironment(env = process.env, userId = process.getuid?.() ?? 1000) {
+    const runtimeDir = env.XDG_RUNTIME_DIR?.trim() || `/run/user/${userId}`;
+    return {
+        ...env,
+        DISPLAY: env.DISPLAY?.trim() || ":0",
+        WAYLAND_DISPLAY: env.WAYLAND_DISPLAY?.trim() || "wayland-0",
+        XDG_RUNTIME_DIR: runtimeDir,
+        PULSE_SERVER: env.PULSE_SERVER?.trim() || "unix:/mnt/wslg/PulseServer",
+        DBUS_SESSION_BUS_ADDRESS: env.DBUS_SESSION_BUS_ADDRESS?.trim() ||
+            `unix:path=${runtimeDir.replace(/\/$/, "")}/bus`,
+    };
+}
+async function queueBrowserWithSystemd(executable, args, env) {
+    await new Promise((resolve, reject) => {
+        const forwardedEnvironment = [
+            "DISPLAY",
+            "WAYLAND_DISPLAY",
+            "XDG_RUNTIME_DIR",
+            "PULSE_SERVER",
+            "DBUS_SESSION_BUS_ADDRESS",
+        ].flatMap((key) => (env[key] ? [`--setenv=${key}=${env[key]}`] : []));
+        const child = spawn("/usr/bin/systemd-run", [
+            "--user",
+            "--collect",
+            "--no-block",
+            "--quiet",
+            ...forwardedEnvironment,
+            executable,
+            ...args,
+        ], {
+            env,
+            stdio: "ignore",
+        });
+        child.once("error", reject);
+        child.once("close", (exitCode) => {
+            if (exitCode === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(`systemd-run could not queue Chromium (exit ${exitCode})`));
+        });
+    });
+}
+export async function openWebUiInWslg(url, options = {}) {
+    const exists = options.exists ?? existsSync;
+    if (!exists("/mnt/wslg")) {
+        throw new Error("WSLg is unavailable at /mnt/wslg");
+    }
+    const candidates = [
+        { executable: "/snap/bin/chromium", args: ["--new-window", url] },
+        { executable: "/usr/bin/chromium-browser", args: ["--new-window", url] },
+        { executable: "/usr/bin/xdg-open", args: [url] },
+    ];
+    const selected = candidates.find((candidate) => exists(candidate.executable));
+    if (!selected) {
+        throw new Error("No supported WSLg Chromium/xdg-open launcher was found");
+    }
+    const spawnBrowser = options.spawnBrowser ?? queueBrowserWithSystemd;
+    await spawnBrowser(selected.executable, selected.args, resolveWslgBrowserEnvironment(options.env, options.userId));
+}
+export async function runRuntimeServiceWebUiAutoOpen(params) {
+    if (!params.settings.enabled) {
+        return { status: "disabled" };
+    }
+    const readiness = await (params.waitUntilReady ?? waitForWebUiReady)(params.settings.healthUrl);
+    if (!readiness.ready) {
+        return {
+            status: "not-ready",
+            url: params.settings.browserUrl,
+            attempts: readiness.attempts,
+            error: readiness.lastError ?? "Web UI did not become ready",
+        };
+    }
+    try {
+        await (params.openBrowser ?? openWebUiInWslg)(params.settings.browserUrl);
+        return {
+            status: "opened",
+            url: params.settings.browserUrl,
+            attempts: readiness.attempts,
+        };
+    }
+    catch (error) {
+        return {
+            status: "open-failed",
+            url: params.settings.browserUrl,
+            attempts: readiness.attempts,
+            error: errorMessage(error),
+        };
+    }
+}

package/dist/src/web-ui/server.d.ts

@@ -0,0 +1,36 @@
+export type WebUiSetupCommandMode = "source" | "package";
+export type WebUiEnvironmentOption = {
+    id: string;
+    label: string;
+    isDefault: boolean;
+};
+type WebUiServerOptions = {
+    host?: string;
+    port?: number;
+    backend?: "runtime" | "bridge";
+    apiBaseUrl?: string;
+    realtimeUrl?: string;
+    healthUrl?: string;
+    agentModeUrl?: string;
+    assistantHostUrl?: string;
+    apiToken?: string;
+    defaultEnvironmentId?: string;
+    environments?: WebUiEnvironmentOption[];
+    appDir?: string;
+    rootDir?: string;
+    configPath?: string;
+    setupCommandMode?: WebUiSetupCommandMode;
+};
+type WebUiServerHandle = {
+    close: () => Promise<void>;
+};
+export declare function resolveWebUiEnvironmentConfig(params: {
+    rootDir: string;
+    configPath?: string;
+    defaultEnvironmentId?: string;
+}): {
+    defaultEnvironmentId: string;
+    environments: WebUiEnvironmentOption[];
+};
+export declare function startWebUiServer(overrides?: WebUiServerOptions): WebUiServerHandle;
+export {};

package/dist/src/web-ui/server.js

@@ -0,0 +1,326 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer, } from "node:http";
+import { normalize, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { WebSocketServer } from "ws";
+import { inspectRuntimeConfigFileWithMeta } from "../runtime/config/loader.js";
+import { loadDotEnvFile } from "../shared/load-dotenv.js";
+import { ExternalBridgeWebBackend } from "./external-bridge-backend.js";
+import { LocalRuntimeWebBackend } from "./local-runtime-backend.js";
+import { resolveWebUiAddress } from "./web-ui-address.js";
+const DEFAULT_WEB_BACKEND = "runtime";
+const DEFAULT_BRIDGE_API_BASE = "http://127.0.0.1:8787/abot/api";
+const DEFAULT_BRIDGE_REALTIME_URL = "ws://127.0.0.1:8787/abot/realtime";
+const DEFAULT_BRIDGE_HEALTH_URL = "http://127.0.0.1:8787/abot/health";
+const DEFAULT_BRIDGE_AGENT_MODE_URL = "http://127.0.0.1:8787/abot/agent-mode";
+const DEFAULT_ASSISTANT_HOST_URL = "http://127.0.0.1:5188";
+const DEFAULT_ENVIRONMENT_ID = "prod";
+const DEFAULT_SETUP_COMMAND_MODE = "source";
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function getConfigString(value, key) {
+    if (!isRecord(value))
+        return "";
+    const raw = value[key];
+    return typeof raw === "string" ? raw.trim() : "";
+}
+function resolveWebApiToken() {
+    return (process.env.LLM_RUNTIME_WEB_API_TOKEN ||
+        process.env.CHAT_API_AUTH_TOKEN ||
+        process.env.CHAT_HISTORY_API_TOKEN ||
+        "");
+}
+export function resolveWebUiEnvironmentConfig(params) {
+    const overrideDefault = params.defaultEnvironmentId?.trim() ?? "";
+    const fallbackDefault = overrideDefault || DEFAULT_ENVIRONMENT_ID;
+    const fallback = {
+        defaultEnvironmentId: fallbackDefault,
+        environments: [
+            {
+                id: fallbackDefault,
+                label: fallbackDefault,
+                isDefault: true,
+            },
+        ],
+    };
+    let config;
+    try {
+        config = inspectRuntimeConfigFileWithMeta(params.rootDir, params.configPath).config;
+    }
+    catch {
+        // Runtime configuration errors belong to the backend catalog response so
+        // the Web UI can start and present the actionable setup error.
+        return fallback;
+    }
+    const environment = isRecord(config.environment)
+        ? config.environment
+        : undefined;
+    const profiles = isRecord(environment?.profiles)
+        ? environment.profiles
+        : undefined;
+    const profileIds = profiles
+        ? Object.keys(profiles).filter((id) => id.trim().length > 0)
+        : [];
+    const configuredDefault = getConfigString(environment, "default");
+    const defaultEnvironmentId = overrideDefault ||
+        configuredDefault ||
+        profileIds[0] ||
+        DEFAULT_ENVIRONMENT_ID;
+    const environmentIds = profileIds.length > 0 ? [...profileIds] : [defaultEnvironmentId];
+    if (!environmentIds.includes(defaultEnvironmentId)) {
+        environmentIds.unshift(defaultEnvironmentId);
+    }
+    return {
+        defaultEnvironmentId,
+        environments: environmentIds.map((id) => ({
+            id,
+            label: id,
+            isDefault: id === defaultEnvironmentId,
+        })),
+    };
+}
+function getOptionsFromEnv() {
+    loadDotEnvFile();
+    const address = resolveWebUiAddress(process.env);
+    const backend = process.env.LLM_RUNTIME_WEB_BACKEND === "bridge"
+        ? "bridge"
+        : DEFAULT_WEB_BACKEND;
+    const rootDir = process.cwd();
+    const configPath = process.env.LLM_RUNTIME_CONFIG_FILE;
+    return {
+        host: address.listenHost,
+        port: address.port,
+        backend,
+        apiBaseUrl: process.env.LLM_RUNTIME_WEB_API_BASE_URL || DEFAULT_BRIDGE_API_BASE,
+        realtimeUrl: process.env.LLM_RUNTIME_WEB_REALTIME_URL || DEFAULT_BRIDGE_REALTIME_URL,
+        healthUrl: process.env.LLM_RUNTIME_WEB_HEALTH_URL || DEFAULT_BRIDGE_HEALTH_URL,
+        agentModeUrl: process.env.LLM_RUNTIME_WEB_AGENT_MODE_URL ||
+            DEFAULT_BRIDGE_AGENT_MODE_URL,
+        assistantHostUrl: process.env.LLM_RUNTIME_WEB_ASSISTANT_HOST_URL ||
+            DEFAULT_ASSISTANT_HOST_URL,
+        apiToken: resolveWebApiToken(),
+        defaultEnvironmentId: process.env.LLM_RUNTIME_WEB_ENVIRONMENT,
+        rootDir,
+        configPath,
+        setupCommandMode: DEFAULT_SETUP_COMMAND_MODE,
+    };
+}
+function resolveAppDir(explicit) {
+    if (explicit)
+        return resolve(explicit);
+    return resolve(process.cwd(), "src/web-ui/app");
+}
+function contentTypeFor(pathname) {
+    if (pathname.endsWith(".html"))
+        return "text/html; charset=utf-8";
+    if (pathname.endsWith(".css"))
+        return "text/css; charset=utf-8";
+    if (pathname.endsWith(".js"))
+        return "text/javascript; charset=utf-8";
+    if (pathname.endsWith(".json"))
+        return "application/json; charset=utf-8";
+    if (pathname.endsWith(".svg"))
+        return "image/svg+xml";
+    if (pathname.endsWith(".png"))
+        return "image/png";
+    return "application/octet-stream";
+}
+function sendJson(res, statusCode, payload) {
+    res.writeHead(statusCode, {
+        "content-type": "application/json; charset=utf-8",
+    });
+    res.end(JSON.stringify(payload));
+}
+function readBody(req) {
+    return new Promise((resolveBody, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolveBody(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+async function serveStaticFile(requestedPath, res, appDir) {
+    const relative = normalize(decodeURIComponent(requestedPath)).replace(/^[/\\]+/, "");
+    const filePath = resolve(appDir, relative);
+    if (!filePath.startsWith(appDir)) {
+        sendJson(res, 403, { ok: false, error: "invalid_static_path" });
+        return true;
+    }
+    try {
+        const fileStat = await stat(filePath);
+        if (!fileStat.isFile())
+            throw new Error("not a file");
+        res.writeHead(200, {
+            "content-type": contentTypeFor(filePath),
+            "cache-control": "no-store",
+        });
+        createReadStream(filePath).pipe(res);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function serveStatic(req, res, appDir) {
+    const incomingUrl = new URL(req.url || "/", "http://localhost");
+    const requestedPath = incomingUrl.pathname === "/" ? "/index.html" : incomingUrl.pathname;
+    if (await serveStaticFile(requestedPath, res, appDir)) {
+        return;
+    }
+    if (!incomingUrl.pathname.includes(".")) {
+        if (await serveStaticFile("/index.html", res, appDir)) {
+            return;
+        }
+    }
+    sendJson(res, 404, { ok: false, error: "not_found" });
+}
+export function startWebUiServer(overrides = {}) {
+    const envOptions = getOptionsFromEnv();
+    const rootDir = overrides.rootDir ?? envOptions.rootDir;
+    const configPath = overrides.configPath ?? envOptions.configPath;
+    const environmentConfig = resolveWebUiEnvironmentConfig({
+        rootDir,
+        configPath,
+        defaultEnvironmentId: overrides.defaultEnvironmentId ?? envOptions.defaultEnvironmentId,
+    });
+    const options = {
+        ...envOptions,
+        ...environmentConfig,
+        ...overrides,
+        appDir: resolveAppDir(overrides.appDir),
+        rootDir,
+        configPath,
+        defaultEnvironmentId: overrides.defaultEnvironmentId ?? environmentConfig.defaultEnvironmentId,
+        environments: overrides.environments ?? environmentConfig.environments,
+    };
+    const wss = new WebSocketServer({ noServer: true });
+    const localRuntimeBackend = options.backend === "runtime"
+        ? new LocalRuntimeWebBackend({
+            rootDir: options.rootDir,
+            configPath: options.configPath,
+            defaultEnvironmentId: options.defaultEnvironmentId,
+        })
+        : null;
+    const externalBridgeBackend = options.backend === "bridge"
+        ? new ExternalBridgeWebBackend({
+            apiBaseUrl: options.apiBaseUrl,
+            realtimeUrl: options.realtimeUrl,
+            healthUrl: options.healthUrl,
+            agentModeUrl: options.agentModeUrl,
+            assistantHostUrl: options.assistantHostUrl,
+            apiToken: options.apiToken,
+        })
+        : null;
+    if (localRuntimeBackend) {
+        wss.on("connection", (client) => {
+            localRuntimeBackend.handleRealtimeConnection(client);
+        });
+    }
+    else if (externalBridgeBackend) {
+        wss.on("connection", (client) => {
+            externalBridgeBackend.handleRealtimeConnection(client);
+        });
+    }
+    const server = createServer((req, res) => {
+        void (async () => {
+            const pathname = new URL(req.url || "/", "http://localhost").pathname;
+            if (pathname === "/web-config") {
+                sendJson(res, 200, {
+                    ok: true,
+                    apiBasePath: "/web-api",
+                    healthPath: "/web-health",
+                    agentModePath: "/web-agent-mode",
+                    assistantHostPath: "/assistant-host",
+                    realtimePath: "/web-realtime",
+                    defaultEnvironmentId: options.defaultEnvironmentId,
+                    environments: options.environments,
+                    authConfigured: Boolean(options.apiToken),
+                    backend: options.backend,
+                    setupCommandMode: options.setupCommandMode,
+                });
+                return;
+            }
+            if (pathname === "/web-health" || pathname === "/web-api/health") {
+                if (localRuntimeBackend) {
+                    await localRuntimeBackend.handleHttp(req, res, pathname);
+                    return;
+                }
+                await externalBridgeBackend?.handleHttp(req, res, pathname);
+                return;
+            }
+            if (pathname === "/web-agent-mode" ||
+                pathname === "/web-api/agent-mode") {
+                if (localRuntimeBackend) {
+                    await localRuntimeBackend.handleHttp(req, res, pathname);
+                    return;
+                }
+                await externalBridgeBackend?.handleHttp(req, res, pathname);
+                return;
+            }
+            if (pathname.startsWith("/web-api/") || pathname === "/web-api") {
+                if (localRuntimeBackend) {
+                    await localRuntimeBackend.handleHttp(req, res, pathname);
+                    return;
+                }
+                await externalBridgeBackend?.handleHttp(req, res, pathname);
+                return;
+            }
+            if (pathname.startsWith("/assistant-host/") ||
+                pathname === "/assistant-host") {
+                if (localRuntimeBackend) {
+                    if (await localRuntimeBackend.handleHttp(req, res, pathname)) {
+                        return;
+                    }
+                }
+                if (await externalBridgeBackend?.handleHttp(req, res, pathname)) {
+                    return;
+                }
+                return;
+            }
+            await serveStatic(req, res, options.appDir);
+        })().catch((error) => {
+            sendJson(res, 500, {
+                ok: false,
+                error: "web_ui_server_error",
+                message: error instanceof Error ? error.message : String(error),
+            });
+        });
+    });
+    server.on("upgrade", (req, socket, head) => {
+        const pathname = new URL(req.url || "/", "http://localhost").pathname;
+        if (pathname !== "/web-realtime") {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            wss.emit("connection", ws, req);
+        });
+    });
+    server.listen(options.port, options.host, () => {
+        console.log(`abot web UI listening on http://${options.host}:${options.port}`);
+        if (localRuntimeBackend) {
+            console.log("using local abot backend");
+        }
+        else if (externalBridgeBackend) {
+            console.log(`using external bridge HTTP ${options.apiBaseUrl}`);
+            console.log(`using external bridge realtime ${options.realtimeUrl}`);
+        }
+    });
+    return {
+        close: () => new Promise((resolveClose, reject) => {
+            wss.close();
+            server.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolveClose();
+            });
+        }),
+    };
+}
+const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === invokedPath) {
+    startWebUiServer();
+}

package/dist/src/web-ui/web-ui-address.d.ts

@@ -0,0 +1,7 @@
+export type WebUiAddress = Readonly<{
+    listenHost: string;
+    port: number;
+    browserUrl: string;
+    healthUrl: string;
+}>;
+export declare function resolveWebUiAddress(env?: NodeJS.ProcessEnv): WebUiAddress;

package/dist/src/web-ui/web-ui-address.js

@@ -0,0 +1,33 @@
+const DEFAULT_WEB_HOST = "127.0.0.1";
+const DEFAULT_WEB_PORT = 5177;
+function resolvePort(value) {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535
+        ? parsed
+        : DEFAULT_WEB_PORT;
+}
+function resolveBrowserHost(listenHost) {
+    const normalized = listenHost.trim().toLowerCase();
+    if (normalized === "0.0.0.0" ||
+        normalized === "::" ||
+        normalized === "[::]" ||
+        normalized === "*") {
+        return DEFAULT_WEB_HOST;
+    }
+    if (listenHost.includes(":") && !listenHost.startsWith("[")) {
+        return `[${listenHost}]`;
+    }
+    return listenHost;
+}
+export function resolveWebUiAddress(env = process.env) {
+    const listenHost = env.LLM_RUNTIME_WEB_HOST?.trim() || DEFAULT_WEB_HOST;
+    const port = resolvePort(env.LLM_RUNTIME_WEB_PORT);
+    const browserHost = resolveBrowserHost(listenHost);
+    const browserUrl = `http://${browserHost}:${port}/`;
+    return {
+        listenHost,
+        port,
+        browserUrl,
+        healthUrl: new URL("web-health", browserUrl).toString(),
+    };
+}