@intent-systems/nexus 2026.1.5-11

package/dist/browser/server-context.js

@@ -0,0 +1,377 @@
+import fs from "node:fs";
+import { createTargetViaCdp, normalizeCdpWsUrl } from "./cdp.js";
+import { isChromeCdpReady, isChromeReachable, launchNexusChrome, resolveNexusUserDataDir, stopNexusChrome, } from "./chrome.js";
+import { resolveProfile } from "./config.js";
+import { resolveTargetIdFromTabs } from "./target-id.js";
+import { movePathToTrash } from "./trash.js";
+/**
+ * Normalize a CDP WebSocket URL to use the correct base URL.
+ */
+function normalizeWsUrl(raw, cdpBaseUrl) {
+    if (!raw)
+        return undefined;
+    try {
+        return normalizeCdpWsUrl(raw, cdpBaseUrl);
+    }
+    catch {
+        return raw;
+    }
+}
+async function fetchJson(url, timeoutMs = 1500, init) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { ...init, signal: ctrl.signal });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return (await res.json());
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+async function fetchOk(url, timeoutMs = 1500, init) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { ...init, signal: ctrl.signal });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+/**
+ * Create a profile-scoped context for browser operations.
+ */
+function createProfileContext(opts, profile) {
+    const state = () => {
+        const current = opts.getState();
+        if (!current)
+            throw new Error("Browser server not started");
+        return current;
+    };
+    const getProfileState = () => {
+        const current = state();
+        let profileState = current.profiles.get(profile.name);
+        if (!profileState) {
+            profileState = { profile, running: null };
+            current.profiles.set(profile.name, profileState);
+        }
+        return profileState;
+    };
+    const setProfileRunning = (running) => {
+        const profileState = getProfileState();
+        profileState.running = running;
+    };
+    const listTabs = async () => {
+        const raw = await fetchJson(`${profile.cdpUrl.replace(/\/$/, "")}/json/list`);
+        return raw
+            .map((t) => ({
+            targetId: t.id ?? "",
+            title: t.title ?? "",
+            url: t.url ?? "",
+            wsUrl: normalizeWsUrl(t.webSocketDebuggerUrl, profile.cdpUrl),
+            type: t.type,
+        }))
+            .filter((t) => Boolean(t.targetId));
+    };
+    const openTab = async (url) => {
+        const createdViaCdp = await createTargetViaCdp({
+            cdpUrl: profile.cdpUrl,
+            url,
+        })
+            .then((r) => r.targetId)
+            .catch(() => null);
+        if (createdViaCdp) {
+            const deadline = Date.now() + 2000;
+            while (Date.now() < deadline) {
+                const tabs = await listTabs().catch(() => []);
+                const found = tabs.find((t) => t.targetId === createdViaCdp);
+                if (found)
+                    return found;
+                await new Promise((r) => setTimeout(r, 100));
+            }
+            return { targetId: createdViaCdp, title: "", url, type: "page" };
+        }
+        const encoded = encodeURIComponent(url);
+        const base = profile.cdpUrl.replace(/\/$/, "");
+        const endpoint = `${base}/json/new?${encoded}`;
+        const created = await fetchJson(endpoint, 1500, {
+            method: "PUT",
+        }).catch(async (err) => {
+            if (String(err).includes("HTTP 405")) {
+                return await fetchJson(endpoint, 1500);
+            }
+            throw err;
+        });
+        if (!created.id)
+            throw new Error("Failed to open tab (missing id)");
+        return {
+            targetId: created.id,
+            title: created.title ?? "",
+            url: created.url ?? url,
+            wsUrl: normalizeWsUrl(created.webSocketDebuggerUrl, base),
+            type: created.type,
+        };
+    };
+    const isReachable = async (timeoutMs = 300) => {
+        const wsTimeout = Math.max(200, Math.min(2000, timeoutMs * 2));
+        return await isChromeCdpReady(profile.cdpUrl, timeoutMs, wsTimeout);
+    };
+    const isHttpReachable = async (timeoutMs = 300) => {
+        return await isChromeReachable(profile.cdpUrl, timeoutMs);
+    };
+    const attachRunning = (running) => {
+        setProfileRunning(running);
+        running.proc.on("exit", () => {
+            // Guard against server teardown (e.g., SIGUSR1 restart)
+            if (!opts.getState())
+                return;
+            const profileState = getProfileState();
+            if (profileState.running?.pid === running.pid) {
+                setProfileRunning(null);
+            }
+        });
+    };
+    const ensureBrowserAvailable = async () => {
+        const current = state();
+        const remoteCdp = !profile.cdpIsLoopback;
+        const profileState = getProfileState();
+        const httpReachable = await isHttpReachable();
+        if (!httpReachable) {
+            if (current.resolved.attachOnly || remoteCdp) {
+                throw new Error(remoteCdp
+                    ? `Remote CDP for profile "${profile.name}" is not reachable at ${profile.cdpUrl}.`
+                    : `Browser attachOnly is enabled and profile "${profile.name}" is not running.`);
+            }
+            const launched = await launchNexusChrome(current.resolved, profile);
+            attachRunning(launched);
+            return;
+        }
+        // Port is reachable - check if we own it
+        if (await isReachable())
+            return;
+        // HTTP responds but WebSocket fails - port in use by something else
+        if (!profileState.running) {
+            throw new Error(`Port ${profile.cdpPort} is in use for profile "${profile.name}" but not by nexus. ` +
+                `Run action=reset-profile profile=${profile.name} to kill the process.`);
+        }
+        // We own it but WebSocket failed - restart
+        if (current.resolved.attachOnly || remoteCdp) {
+            throw new Error(remoteCdp
+                ? `Remote CDP websocket for profile "${profile.name}" is not reachable.`
+                : `Browser attachOnly is enabled and CDP websocket for profile "${profile.name}" is not reachable.`);
+        }
+        await stopNexusChrome(profileState.running);
+        setProfileRunning(null);
+        const relaunched = await launchNexusChrome(current.resolved, profile);
+        attachRunning(relaunched);
+        if (!(await isReachable(600))) {
+            throw new Error(`Chrome CDP websocket for profile "${profile.name}" is not reachable after restart.`);
+        }
+    };
+    const ensureTabAvailable = async (targetId) => {
+        await ensureBrowserAvailable();
+        const tabs1 = await listTabs();
+        if (tabs1.length === 0) {
+            await openTab("about:blank");
+        }
+        const tabs = await listTabs();
+        const chosen = targetId
+            ? (() => {
+                const resolved = resolveTargetIdFromTabs(targetId, tabs);
+                if (!resolved.ok) {
+                    if (resolved.reason === "ambiguous")
+                        return "AMBIGUOUS";
+                    return null;
+                }
+                return tabs.find((t) => t.targetId === resolved.targetId) ?? null;
+            })()
+            : (tabs.at(0) ?? null);
+        if (chosen === "AMBIGUOUS") {
+            throw new Error("ambiguous target id prefix");
+        }
+        if (!chosen?.wsUrl)
+            throw new Error("tab not found");
+        return chosen;
+    };
+    const focusTab = async (targetId) => {
+        const base = profile.cdpUrl.replace(/\/$/, "");
+        const tabs = await listTabs();
+        const resolved = resolveTargetIdFromTabs(targetId, tabs);
+        if (!resolved.ok) {
+            if (resolved.reason === "ambiguous") {
+                throw new Error("ambiguous target id prefix");
+            }
+            throw new Error("tab not found");
+        }
+        await fetchOk(`${base}/json/activate/${resolved.targetId}`);
+    };
+    const closeTab = async (targetId) => {
+        const base = profile.cdpUrl.replace(/\/$/, "");
+        const tabs = await listTabs();
+        const resolved = resolveTargetIdFromTabs(targetId, tabs);
+        if (!resolved.ok) {
+            if (resolved.reason === "ambiguous") {
+                throw new Error("ambiguous target id prefix");
+            }
+            throw new Error("tab not found");
+        }
+        await fetchOk(`${base}/json/close/${resolved.targetId}`);
+    };
+    const stopRunningBrowser = async () => {
+        const profileState = getProfileState();
+        if (!profileState.running)
+            return { stopped: false };
+        await stopNexusChrome(profileState.running);
+        setProfileRunning(null);
+        return { stopped: true };
+    };
+    const resetProfile = async () => {
+        if (!profile.cdpIsLoopback) {
+            throw new Error(`reset-profile is only supported for local profiles (profile "${profile.name}" is remote).`);
+        }
+        const userDataDir = resolveNexusUserDataDir(profile.name);
+        const profileState = getProfileState();
+        const httpReachable = await isHttpReachable(300);
+        if (httpReachable && !profileState.running) {
+            // Port in use but not by us - kill it
+            try {
+                const mod = await import("./pw-ai.js");
+                await mod.closePlaywrightBrowserConnection();
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (profileState.running) {
+            await stopRunningBrowser();
+        }
+        try {
+            const mod = await import("./pw-ai.js");
+            await mod.closePlaywrightBrowserConnection();
+        }
+        catch {
+            // ignore
+        }
+        if (!fs.existsSync(userDataDir)) {
+            return { moved: false, from: userDataDir };
+        }
+        const moved = await movePathToTrash(userDataDir);
+        return { moved: true, from: userDataDir, to: moved };
+    };
+    return {
+        profile,
+        ensureBrowserAvailable,
+        ensureTabAvailable,
+        isHttpReachable,
+        isReachable,
+        listTabs,
+        openTab,
+        focusTab,
+        closeTab,
+        stopRunningBrowser,
+        resetProfile,
+    };
+}
+export function createBrowserRouteContext(opts) {
+    const state = () => {
+        const current = opts.getState();
+        if (!current)
+            throw new Error("Browser server not started");
+        return current;
+    };
+    const forProfile = (profileName) => {
+        const current = state();
+        const name = profileName ?? current.resolved.defaultProfile;
+        const profile = resolveProfile(current.resolved, name);
+        if (!profile) {
+            const available = Object.keys(current.resolved.profiles).join(", ");
+            throw new Error(`Profile "${name}" not found. Available profiles: ${available || "(none)"}`);
+        }
+        return createProfileContext(opts, profile);
+    };
+    const listProfiles = async () => {
+        const current = state();
+        const result = [];
+        for (const name of Object.keys(current.resolved.profiles)) {
+            const profileState = current.profiles.get(name);
+            const profile = resolveProfile(current.resolved, name);
+            if (!profile)
+                continue;
+            let tabCount = 0;
+            let running = false;
+            if (profileState?.running) {
+                running = true;
+                try {
+                    const ctx = createProfileContext(opts, profile);
+                    const tabs = await ctx.listTabs();
+                    tabCount = tabs.filter((t) => t.type === "page").length;
+                }
+                catch {
+                    // Browser might not be responsive
+                }
+            }
+            else {
+                // Check if something is listening on the port
+                try {
+                    const reachable = await isChromeReachable(profile.cdpUrl, 200);
+                    if (reachable) {
+                        running = true;
+                        const ctx = createProfileContext(opts, profile);
+                        const tabs = await ctx.listTabs().catch(() => []);
+                        tabCount = tabs.filter((t) => t.type === "page").length;
+                    }
+                }
+                catch {
+                    // Not reachable
+                }
+            }
+            result.push({
+                name,
+                cdpPort: profile.cdpPort,
+                cdpUrl: profile.cdpUrl,
+                color: profile.color,
+                running,
+                tabCount,
+                isDefault: name === current.resolved.defaultProfile,
+                isRemote: !profile.cdpIsLoopback,
+            });
+        }
+        return result;
+    };
+    // Create default profile context for backward compatibility
+    const getDefaultContext = () => forProfile();
+    const mapTabError = (err) => {
+        const msg = String(err);
+        if (msg.includes("ambiguous target id prefix")) {
+            return { status: 409, message: "ambiguous target id prefix" };
+        }
+        if (msg.includes("tab not found")) {
+            return { status: 404, message: "tab not found" };
+        }
+        if (msg.includes("not found")) {
+            return { status: 404, message: msg };
+        }
+        return null;
+    };
+    return {
+        state,
+        forProfile,
+        listProfiles,
+        // Legacy methods delegate to default profile
+        ensureBrowserAvailable: () => getDefaultContext().ensureBrowserAvailable(),
+        ensureTabAvailable: (targetId) => getDefaultContext().ensureTabAvailable(targetId),
+        isHttpReachable: (timeoutMs) => getDefaultContext().isHttpReachable(timeoutMs),
+        isReachable: (timeoutMs) => getDefaultContext().isReachable(timeoutMs),
+        listTabs: () => getDefaultContext().listTabs(),
+        openTab: (url) => getDefaultContext().openTab(url),
+        focusTab: (targetId) => getDefaultContext().focusTab(targetId),
+        closeTab: (targetId) => getDefaultContext().closeTab(targetId),
+        stopRunningBrowser: () => getDefaultContext().stopRunningBrowser(),
+        resetProfile: () => getDefaultContext().resetProfile(),
+        mapTabError,
+    };
+}

package/dist/browser/server.js

@@ -0,0 +1,81 @@
+import express from "express";
+import { loadConfig } from "../config/config.js";
+import { createSubsystemLogger } from "../logging.js";
+import { resolveBrowserConfig, shouldStartLocalBrowserServer, } from "./config.js";
+import { registerBrowserRoutes } from "./routes/index.js";
+import { createBrowserRouteContext, } from "./server-context.js";
+let state = null;
+const log = createSubsystemLogger("browser");
+const logServer = log.child("server");
+export async function startBrowserControlServerFromConfig() {
+    if (state)
+        return state;
+    const cfg = loadConfig();
+    const resolved = resolveBrowserConfig(cfg.browser);
+    if (!resolved.enabled)
+        return null;
+    if (!shouldStartLocalBrowserServer(resolved)) {
+        logServer.info(`browser control URL is non-loopback (${resolved.controlUrl}); skipping local server start`);
+        return null;
+    }
+    const app = express();
+    app.use(express.json({ limit: "1mb" }));
+    const ctx = createBrowserRouteContext({
+        getState: () => state,
+    });
+    registerBrowserRoutes(app, ctx);
+    const port = resolved.controlPort;
+    const server = await new Promise((resolve, reject) => {
+        const s = app.listen(port, "127.0.0.1", () => resolve(s));
+        s.once("error", reject);
+    }).catch((err) => {
+        logServer.error(`nexus browser server failed to bind 127.0.0.1:${port}: ${String(err)}`);
+        return null;
+    });
+    if (!server)
+        return null;
+    state = {
+        server,
+        port,
+        resolved,
+        profiles: new Map(),
+    };
+    logServer.info(`Browser control listening on http://127.0.0.1:${port}/`);
+    return state;
+}
+export async function stopBrowserControlServer() {
+    const current = state;
+    if (!current)
+        return;
+    const ctx = createBrowserRouteContext({
+        getState: () => state,
+    });
+    try {
+        const current = state;
+        if (current) {
+            for (const name of Object.keys(current.resolved.profiles)) {
+                try {
+                    await ctx.forProfile(name).stopRunningBrowser();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    catch (err) {
+        logServer.warn(`nexus browser stop failed: ${String(err)}`);
+    }
+    await new Promise((resolve) => {
+        current.server.close(() => resolve());
+    });
+    state = null;
+    // Optional: Playwright is not always available (e.g. embedded gateway builds).
+    try {
+        const mod = await import("./pw-ai.js");
+        await mod.closePlaywrightBrowserConnection();
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/browser/target-id.js

@@ -0,0 +1,18 @@
+export function resolveTargetIdFromTabs(input, tabs) {
+    const needle = input.trim();
+    if (!needle)
+        return { ok: false, reason: "not_found" };
+    const exact = tabs.find((t) => t.targetId === needle);
+    if (exact)
+        return { ok: true, targetId: exact.targetId };
+    const lower = needle.toLowerCase();
+    const matches = tabs
+        .map((t) => t.targetId)
+        .filter((id) => id.toLowerCase().startsWith(lower));
+    const only = matches.length === 1 ? matches[0] : undefined;
+    if (only)
+        return { ok: true, targetId: only };
+    if (matches.length === 0)
+        return { ok: false, reason: "not_found" };
+    return { ok: false, reason: "ambiguous", matches };
+}

package/dist/browser/trash.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runExec } from "../process/exec.js";
+export async function movePathToTrash(targetPath) {
+    try {
+        await runExec("trash", [targetPath], { timeoutMs: 10_000 });
+        return targetPath;
+    }
+    catch {
+        const trashDir = path.join(os.homedir(), ".Trash");
+        fs.mkdirSync(trashDir, { recursive: true });
+        const base = path.basename(targetPath);
+        let dest = path.join(trashDir, `${base}-${Date.now()}`);
+        if (fs.existsSync(dest)) {
+            dest = path.join(trashDir, `${base}-${Date.now()}-${Math.random()}`);
+        }
+        fs.renameSync(targetPath, dest);
+        return dest;
+    }
+}