@intent-systems/nexus 2026.1.5-3

package/dist/browser/chrome.js

@@ -0,0 +1,432 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import WebSocket from "ws";
+import { ensurePortAvailable } from "../infra/ports.js";
+import { createSubsystemLogger } from "../logging.js";
+import { CONFIG_DIR } from "../utils.js";
+import { normalizeCdpWsUrl } from "./cdp.js";
+import { DEFAULT_NEXUS_BROWSER_COLOR, DEFAULT_NEXUS_BROWSER_PROFILE_NAME } from "./constants.js";
+const log = createSubsystemLogger("browser").child("chrome");
+function exists(filePath) {
+    try {
+        return fs.existsSync(filePath);
+    }
+    catch {
+        return false;
+    }
+}
+export function findChromeExecutableMac() {
+    const candidates = [
+        {
+            kind: "canary",
+            path: "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+        },
+        {
+            kind: "canary",
+            path: path.join(os.homedir(), "Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"),
+        },
+        {
+            kind: "chromium",
+            path: "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        },
+        {
+            kind: "chromium",
+            path: path.join(os.homedir(), "Applications/Chromium.app/Contents/MacOS/Chromium"),
+        },
+        {
+            kind: "chrome",
+            path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        },
+        {
+            kind: "chrome",
+            path: path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+        },
+    ];
+    for (const candidate of candidates) {
+        if (exists(candidate.path))
+            return candidate;
+    }
+    return null;
+}
+export function findChromeExecutableLinux() {
+    const candidates = [
+        { kind: "chrome", path: "/usr/bin/google-chrome" },
+        { kind: "chrome", path: "/usr/bin/google-chrome-stable" },
+        { kind: "chromium", path: "/usr/bin/chromium" },
+        { kind: "chromium", path: "/usr/bin/chromium-browser" },
+        { kind: "chromium", path: "/snap/bin/chromium" },
+        { kind: "chrome", path: "/usr/bin/chrome" },
+    ];
+    for (const candidate of candidates) {
+        if (exists(candidate.path))
+            return candidate;
+    }
+    return null;
+}
+function resolveBrowserExecutable(resolved) {
+    if (resolved.executablePath) {
+        if (!exists(resolved.executablePath)) {
+            throw new Error(`browser.executablePath not found: ${resolved.executablePath}`);
+        }
+        return { kind: "custom", path: resolved.executablePath };
+    }
+    if (process.platform === "darwin")
+        return findChromeExecutableMac();
+    if (process.platform === "linux")
+        return findChromeExecutableLinux();
+    return null;
+}
+export function resolveNexusUserDataDir(profileName = DEFAULT_NEXUS_BROWSER_PROFILE_NAME) {
+    return path.join(CONFIG_DIR, "browser", profileName, "user-data");
+}
+function decoratedMarkerPath(userDataDir) {
+    return path.join(userDataDir, ".nexus-profile-decorated");
+}
+function safeReadJson(filePath) {
+    try {
+        if (!exists(filePath))
+            return null;
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function safeWriteJson(filePath, data) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+function cdpUrlForPort(cdpPort) {
+    return `http://127.0.0.1:${cdpPort}`;
+}
+function setDeep(obj, keys, value) {
+    let node = obj;
+    for (const key of keys.slice(0, -1)) {
+        const next = node[key];
+        if (typeof next !== "object" || next === null || Array.isArray(next)) {
+            node[key] = {};
+        }
+        node = node[key];
+    }
+    node[keys[keys.length - 1] ?? ""] = value;
+}
+function parseHexRgbToSignedArgbInt(hex) {
+    const cleaned = hex.trim().replace(/^#/, "");
+    if (!/^[0-9a-fA-F]{6}$/.test(cleaned))
+        return null;
+    const rgb = Number.parseInt(cleaned, 16);
+    const argbUnsigned = (0xff << 24) | rgb;
+    // Chrome stores colors as signed 32-bit ints (SkColor).
+    return argbUnsigned > 0x7fffffff
+        ? argbUnsigned - 0x1_0000_0000
+        : argbUnsigned;
+}
+function isProfileDecorated(userDataDir, desiredName, desiredColorHex) {
+    const desiredColorInt = parseHexRgbToSignedArgbInt(desiredColorHex);
+    const localStatePath = path.join(userDataDir, "Local State");
+    const preferencesPath = path.join(userDataDir, "Default", "Preferences");
+    const localState = safeReadJson(localStatePath);
+    const profile = localState?.profile;
+    const infoCache = typeof profile === "object" && profile !== null && !Array.isArray(profile)
+        ? profile.info_cache
+        : null;
+    const info = typeof infoCache === "object" &&
+        infoCache !== null &&
+        !Array.isArray(infoCache) &&
+        typeof infoCache.Default === "object" &&
+        infoCache.Default !== null &&
+        !Array.isArray(infoCache.Default)
+        ? infoCache.Default
+        : null;
+    const prefs = safeReadJson(preferencesPath);
+    const browserTheme = (() => {
+        const browser = prefs?.browser;
+        const theme = typeof browser === "object" && browser !== null && !Array.isArray(browser)
+            ? browser.theme
+            : null;
+        return typeof theme === "object" && theme !== null && !Array.isArray(theme)
+            ? theme
+            : null;
+    })();
+    const autogeneratedTheme = (() => {
+        const autogenerated = prefs?.autogenerated;
+        const theme = typeof autogenerated === "object" &&
+            autogenerated !== null &&
+            !Array.isArray(autogenerated)
+            ? autogenerated.theme
+            : null;
+        return typeof theme === "object" && theme !== null && !Array.isArray(theme)
+            ? theme
+            : null;
+    })();
+    const nameOk = typeof info?.name === "string" ? info.name === desiredName : true;
+    if (desiredColorInt == null) {
+        // If the user provided a non-#RRGGBB value, we can only do best-effort.
+        return nameOk;
+    }
+    const localSeedOk = typeof info?.profile_color_seed === "number"
+        ? info.profile_color_seed === desiredColorInt
+        : false;
+    const prefOk = (typeof browserTheme?.user_color2 === "number" &&
+        browserTheme.user_color2 === desiredColorInt) ||
+        (typeof autogeneratedTheme?.color === "number" &&
+            autogeneratedTheme.color === desiredColorInt);
+    return nameOk && localSeedOk && prefOk;
+}
+/**
+ * Best-effort profile decoration (name + lobster-orange). Chrome preference keys
+ * vary by version; we keep this conservative and idempotent.
+ */
+export function decorateNexusProfile(userDataDir, opts) {
+    const desiredName = opts?.name ?? DEFAULT_NEXUS_BROWSER_PROFILE_NAME;
+    const desiredColor = (opts?.color ?? DEFAULT_NEXUS_BROWSER_COLOR).toUpperCase();
+    const desiredColorInt = parseHexRgbToSignedArgbInt(desiredColor);
+    const localStatePath = path.join(userDataDir, "Local State");
+    const preferencesPath = path.join(userDataDir, "Default", "Preferences");
+    const localState = safeReadJson(localStatePath) ?? {};
+    // Common-ish shape: profile.info_cache.Default
+    setDeep(localState, ["profile", "info_cache", "Default", "name"], desiredName);
+    setDeep(localState, ["profile", "info_cache", "Default", "shortcut_name"], desiredName);
+    setDeep(localState, ["profile", "info_cache", "Default", "user_name"], desiredName);
+    // Color keys are best-effort (Chrome changes these frequently).
+    setDeep(localState, ["profile", "info_cache", "Default", "profile_color"], desiredColor);
+    setDeep(localState, ["profile", "info_cache", "Default", "user_color"], desiredColor);
+    if (desiredColorInt != null) {
+        // These are the fields Chrome actually uses for profile/avatar tinting.
+        setDeep(localState, ["profile", "info_cache", "Default", "profile_color_seed"], desiredColorInt);
+        setDeep(localState, ["profile", "info_cache", "Default", "profile_highlight_color"], desiredColorInt);
+        setDeep(localState, ["profile", "info_cache", "Default", "default_avatar_fill_color"], desiredColorInt);
+        setDeep(localState, ["profile", "info_cache", "Default", "default_avatar_stroke_color"], desiredColorInt);
+    }
+    safeWriteJson(localStatePath, localState);
+    const prefs = safeReadJson(preferencesPath) ?? {};
+    setDeep(prefs, ["profile", "name"], desiredName);
+    setDeep(prefs, ["profile", "profile_color"], desiredColor);
+    setDeep(prefs, ["profile", "user_color"], desiredColor);
+    if (desiredColorInt != null) {
+        // Chrome refresh stores the autogenerated theme in these prefs (SkColor ints).
+        setDeep(prefs, ["autogenerated", "theme", "color"], desiredColorInt);
+        // User-selected browser theme color (pref name: browser.theme.user_color2).
+        setDeep(prefs, ["browser", "theme", "user_color2"], desiredColorInt);
+    }
+    safeWriteJson(preferencesPath, prefs);
+    try {
+        fs.writeFileSync(decoratedMarkerPath(userDataDir), `${Date.now()}\n`, "utf-8");
+    }
+    catch {
+        // ignore
+    }
+}
+export async function isChromeReachable(cdpUrl, timeoutMs = 500) {
+    const version = await fetchChromeVersion(cdpUrl, timeoutMs);
+    return Boolean(version);
+}
+async function fetchChromeVersion(cdpUrl, timeoutMs = 500) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const base = cdpUrl.replace(/\/$/, "");
+        const res = await fetch(`${base}/json/version`, {
+            signal: ctrl.signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        if (!data || typeof data !== "object")
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+export async function getChromeWebSocketUrl(cdpUrl, timeoutMs = 500) {
+    const version = await fetchChromeVersion(cdpUrl, timeoutMs);
+    const wsUrl = String(version?.webSocketDebuggerUrl ?? "").trim();
+    if (!wsUrl)
+        return null;
+    return normalizeCdpWsUrl(wsUrl, cdpUrl);
+}
+async function canOpenWebSocket(wsUrl, timeoutMs = 800) {
+    return await new Promise((resolve) => {
+        const ws = new WebSocket(wsUrl, { handshakeTimeout: timeoutMs });
+        const timer = setTimeout(() => {
+            try {
+                ws.terminate();
+            }
+            catch {
+                // ignore
+            }
+            resolve(false);
+        }, Math.max(50, timeoutMs + 25));
+        ws.once("open", () => {
+            clearTimeout(timer);
+            try {
+                ws.close();
+            }
+            catch {
+                // ignore
+            }
+            resolve(true);
+        });
+        ws.once("error", () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+export async function isChromeCdpReady(cdpUrl, timeoutMs = 500, handshakeTimeoutMs = 800) {
+    const wsUrl = await getChromeWebSocketUrl(cdpUrl, timeoutMs);
+    if (!wsUrl)
+        return false;
+    return await canOpenWebSocket(wsUrl, handshakeTimeoutMs);
+}
+export async function launchNexusChrome(resolved, profile) {
+    if (!profile.cdpIsLoopback) {
+        throw new Error(`Profile "${profile.name}" is remote; cannot launch local Chrome.`);
+    }
+    await ensurePortAvailable(profile.cdpPort);
+    const exe = resolveBrowserExecutable(resolved);
+    if (!exe) {
+        throw new Error("No supported browser found (Chrome/Chromium on macOS or Linux).");
+    }
+    const userDataDir = resolveNexusUserDataDir(profile.name);
+    fs.mkdirSync(userDataDir, { recursive: true });
+    const needsDecorate = !isProfileDecorated(userDataDir, profile.name, (profile.color ?? DEFAULT_NEXUS_BROWSER_COLOR).toUpperCase());
+    // First launch to create preference files if missing, then decorate and relaunch.
+    const spawnOnce = () => {
+        const args = [
+            `--remote-debugging-port=${profile.cdpPort}`,
+            `--user-data-dir=${userDataDir}`,
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-sync",
+            "--disable-background-networking",
+            "--disable-component-update",
+            "--disable-features=Translate,MediaRouter",
+            "--password-store=basic",
+        ];
+        if (resolved.headless) {
+            // Best-effort; older Chromes may ignore.
+            args.push("--headless=new");
+            args.push("--disable-gpu");
+        }
+        if (resolved.noSandbox) {
+            args.push("--no-sandbox");
+            args.push("--disable-setuid-sandbox");
+        }
+        if (process.platform === "linux") {
+            args.push("--disable-dev-shm-usage");
+        }
+        // Always open a blank tab to ensure a target exists.
+        args.push("about:blank");
+        return spawn(exe.path, args, {
+            stdio: "pipe",
+            env: {
+                ...process.env,
+                // Reduce accidental sharing with the user's env.
+                HOME: os.homedir(),
+            },
+        });
+    };
+    const startedAt = Date.now();
+    const localStatePath = path.join(userDataDir, "Local State");
+    const preferencesPath = path.join(userDataDir, "Default", "Preferences");
+    const needsBootstrap = !exists(localStatePath) || !exists(preferencesPath);
+    // If the profile doesn't exist yet, bootstrap it once so Chrome creates defaults.
+    // Then decorate (if needed) before the "real" run.
+    if (needsBootstrap) {
+        const bootstrap = spawnOnce();
+        const deadline = Date.now() + 10_000;
+        while (Date.now() < deadline) {
+            if (exists(localStatePath) && exists(preferencesPath))
+                break;
+            await new Promise((r) => setTimeout(r, 100));
+        }
+        try {
+            bootstrap.kill("SIGTERM");
+        }
+        catch {
+            // ignore
+        }
+        const exitDeadline = Date.now() + 5000;
+        while (Date.now() < exitDeadline) {
+            if (bootstrap.exitCode != null)
+                break;
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    }
+    if (needsDecorate) {
+        try {
+            decorateNexusProfile(userDataDir, {
+                name: profile.name,
+                color: profile.color,
+            });
+            log.info(`🦞 nexus browser profile decorated (${profile.color})`);
+        }
+        catch (err) {
+            log.warn(`nexus browser profile decoration failed: ${String(err)}`);
+        }
+    }
+    const proc = spawnOnce();
+    // Wait for CDP to come up.
+    const readyDeadline = Date.now() + 15_000;
+    while (Date.now() < readyDeadline) {
+        if (await isChromeReachable(profile.cdpUrl, 500))
+            break;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    if (!(await isChromeReachable(profile.cdpUrl, 500))) {
+        try {
+            proc.kill("SIGKILL");
+        }
+        catch {
+            // ignore
+        }
+        throw new Error(`Failed to start Chrome CDP on port ${profile.cdpPort} for profile "${profile.name}".`);
+    }
+    const pid = proc.pid ?? -1;
+    log.info(`🦞 nexus browser started (${exe.kind}) profile "${profile.name}" on 127.0.0.1:${profile.cdpPort} (pid ${pid})`);
+    return {
+        pid,
+        exe,
+        userDataDir,
+        cdpPort: profile.cdpPort,
+        startedAt,
+        proc,
+    };
+}
+export async function stopNexusChrome(running, timeoutMs = 2500) {
+    const proc = running.proc;
+    if (proc.killed)
+        return;
+    try {
+        proc.kill("SIGTERM");
+    }
+    catch {
+        // ignore
+    }
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (!proc.exitCode && proc.killed)
+            break;
+        if (!(await isChromeReachable(cdpUrlForPort(running.cdpPort), 200)))
+            return;
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    try {
+        proc.kill("SIGKILL");
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/browser/client-actions-core.js

@@ -0,0 +1,67 @@
+import { fetchBrowserJson } from "./client-fetch.js";
+function buildProfileQuery(profile) {
+    return profile ? `?profile=${encodeURIComponent(profile)}` : "";
+}
+export async function browserNavigate(baseUrl, opts) {
+    const q = buildProfileQuery(opts.profile);
+    return await fetchBrowserJson(`${baseUrl}/navigate${q}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ url: opts.url, targetId: opts.targetId }),
+        timeoutMs: 20000,
+    });
+}
+export async function browserArmDialog(baseUrl, opts) {
+    const q = buildProfileQuery(opts.profile);
+    return await fetchBrowserJson(`${baseUrl}/hooks/dialog${q}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            accept: opts.accept,
+            promptText: opts.promptText,
+            targetId: opts.targetId,
+            timeoutMs: opts.timeoutMs,
+        }),
+        timeoutMs: 20000,
+    });
+}
+export async function browserArmFileChooser(baseUrl, opts) {
+    const q = buildProfileQuery(opts.profile);
+    return await fetchBrowserJson(`${baseUrl}/hooks/file-chooser${q}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            paths: opts.paths,
+            ref: opts.ref,
+            inputRef: opts.inputRef,
+            element: opts.element,
+            targetId: opts.targetId,
+            timeoutMs: opts.timeoutMs,
+        }),
+        timeoutMs: 20000,
+    });
+}
+export async function browserAct(baseUrl, req, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    return await fetchBrowserJson(`${baseUrl}/act${q}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(req),
+        timeoutMs: 20000,
+    });
+}
+export async function browserScreenshotAction(baseUrl, opts) {
+    const q = buildProfileQuery(opts.profile);
+    return await fetchBrowserJson(`${baseUrl}/screenshot${q}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            targetId: opts.targetId,
+            fullPage: opts.fullPage,
+            ref: opts.ref,
+            element: opts.element,
+            type: opts.type,
+        }),
+        timeoutMs: 20000,
+    });
+}

package/dist/browser/client-actions-observe.js

@@ -0,0 +1,24 @@
+import { fetchBrowserJson } from "./client-fetch.js";
+function buildProfileQuery(profile) {
+    return profile ? `?profile=${encodeURIComponent(profile)}` : "";
+}
+export async function browserConsoleMessages(baseUrl, opts = {}) {
+    const q = new URLSearchParams();
+    if (opts.level)
+        q.set("level", opts.level);
+    if (opts.targetId)
+        q.set("targetId", opts.targetId);
+    if (opts.profile)
+        q.set("profile", opts.profile);
+    const suffix = q.toString() ? `?${q.toString()}` : "";
+    return await fetchBrowserJson(`${baseUrl}/console${suffix}`, { timeoutMs: 20000 });
+}
+export async function browserPdfSave(baseUrl, opts = {}) {
+    const q = buildProfileQuery(opts.profile);
+    return await fetchBrowserJson(`${baseUrl}/pdf${q}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ targetId: opts.targetId }),
+        timeoutMs: 20000,
+    });
+}

package/dist/browser/client-actions-types.js

@@ -0,0 +1 @@
+export {};

package/dist/browser/client-actions.js

@@ -0,0 +1,3 @@
+export * from "./client-actions-core.js";
+export * from "./client-actions-observe.js";
+export * from "./client-actions-types.js";

package/dist/browser/client-fetch.js

@@ -0,0 +1,43 @@
+import { extractErrorCode, formatErrorMessage } from "../infra/errors.js";
+function unwrapCause(err) {
+    if (!err || typeof err !== "object")
+        return null;
+    const cause = err.cause;
+    return cause ?? null;
+}
+function enhanceBrowserFetchError(url, err, timeoutMs) {
+    const cause = unwrapCause(err);
+    const code = extractErrorCode(cause) ?? extractErrorCode(err) ?? "";
+    const hint = "Start (or restart) the Nexus gateway (Nexus.app menubar, or `nexus gateway`) and try again.";
+    if (code === "ECONNREFUSED") {
+        return new Error(`Can't reach the nexus browser control server at ${url} (connection refused). ${hint}`);
+    }
+    if (code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT") {
+        return new Error(`Can't reach the nexus browser control server at ${url} (timed out after ${timeoutMs}ms). ${hint}`);
+    }
+    const msg = formatErrorMessage(err);
+    if (msg.toLowerCase().includes("abort")) {
+        return new Error(`Can't reach the nexus browser control server at ${url} (timed out after ${timeoutMs}ms). ${hint}`);
+    }
+    return new Error(`Can't reach the nexus browser control server at ${url}. ${hint} (${msg})`);
+}
+export async function fetchBrowserJson(url, init) {
+    const timeoutMs = init?.timeoutMs ?? 5000;
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    let res;
+    try {
+        res = await fetch(url, { ...init, signal: ctrl.signal });
+    }
+    catch (err) {
+        throw enhanceBrowserFetchError(url, err, timeoutMs);
+    }
+    finally {
+        clearTimeout(t);
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(text ? `${res.status}: ${text}` : `HTTP ${res.status}`);
+    }
+    return (await res.json());
+}

package/dist/browser/client.js

@@ -0,0 +1,105 @@
+import { loadConfig } from "../config/config.js";
+import { fetchBrowserJson } from "./client-fetch.js";
+import { resolveBrowserConfig } from "./config.js";
+export function resolveBrowserControlUrl(overrideUrl) {
+    const cfg = loadConfig();
+    const resolved = resolveBrowserConfig(cfg.browser);
+    const url = overrideUrl?.trim() ? overrideUrl.trim() : resolved.controlUrl;
+    return url.replace(/\/$/, "");
+}
+function buildProfileQuery(profile) {
+    return profile ? `?profile=${encodeURIComponent(profile)}` : "";
+}
+export async function browserStatus(baseUrl, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    return await fetchBrowserJson(`${baseUrl}/${q}`, {
+        timeoutMs: 1500,
+    });
+}
+export async function browserProfiles(baseUrl) {
+    const res = await fetchBrowserJson(`${baseUrl}/profiles`, { timeoutMs: 3000 });
+    return res.profiles ?? [];
+}
+export async function browserStart(baseUrl, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    await fetchBrowserJson(`${baseUrl}/start${q}`, {
+        method: "POST",
+        timeoutMs: 15000,
+    });
+}
+export async function browserStop(baseUrl, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    await fetchBrowserJson(`${baseUrl}/stop${q}`, {
+        method: "POST",
+        timeoutMs: 15000,
+    });
+}
+export async function browserResetProfile(baseUrl, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    return await fetchBrowserJson(`${baseUrl}/reset-profile${q}`, {
+        method: "POST",
+        timeoutMs: 20000,
+    });
+}
+export async function browserCreateProfile(baseUrl, opts) {
+    return await fetchBrowserJson(`${baseUrl}/profiles/create`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            name: opts.name,
+            color: opts.color,
+            cdpUrl: opts.cdpUrl,
+        }),
+        timeoutMs: 10000,
+    });
+}
+export async function browserDeleteProfile(baseUrl, profile) {
+    return await fetchBrowserJson(`${baseUrl}/profiles/${encodeURIComponent(profile)}`, {
+        method: "DELETE",
+        timeoutMs: 20000,
+    });
+}
+export async function browserTabs(baseUrl, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    const res = await fetchBrowserJson(`${baseUrl}/tabs${q}`, { timeoutMs: 3000 });
+    return res.tabs ?? [];
+}
+export async function browserOpenTab(baseUrl, url, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    return await fetchBrowserJson(`${baseUrl}/tabs/open${q}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ url }),
+        timeoutMs: 15000,
+    });
+}
+export async function browserFocusTab(baseUrl, targetId, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    await fetchBrowserJson(`${baseUrl}/tabs/focus${q}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ targetId }),
+        timeoutMs: 5000,
+    });
+}
+export async function browserCloseTab(baseUrl, targetId, opts) {
+    const q = buildProfileQuery(opts?.profile);
+    await fetchBrowserJson(`${baseUrl}/tabs/${encodeURIComponent(targetId)}${q}`, {
+        method: "DELETE",
+        timeoutMs: 5000,
+    });
+}
+export async function browserSnapshot(baseUrl, opts) {
+    const q = new URLSearchParams();
+    q.set("format", opts.format);
+    if (opts.targetId)
+        q.set("targetId", opts.targetId);
+    if (typeof opts.limit === "number")
+        q.set("limit", String(opts.limit));
+    if (opts.profile)
+        q.set("profile", opts.profile);
+    return await fetchBrowserJson(`${baseUrl}/snapshot?${q.toString()}`, {
+        timeoutMs: 20000,
+    });
+}
+// Actions beyond the basic read-only commands live in client-actions.ts.