@rynx-ai/cli 0.1.10

package/dist/control-endpoint.d.ts

@@ -0,0 +1,29 @@
+export interface DaemonControlEndpoint {
+    origin: string;
+    pid: number;
+    managementToken: string;
+    distribution?: "app" | "standalone";
+    productVersion?: string;
+    buildId?: string;
+    daemonLifecycle?: "follow-app" | "resident" | "standalone";
+    managementProtocol?: {
+        current: number;
+        minimumCompatible: number;
+    };
+}
+export interface ResolveDaemonControlEndpointOptions {
+    signal?: AbortSignal;
+    probe?: boolean;
+}
+/**
+ * Read the endpoint published by the App- or supervisor-owned daemon.
+ *
+ * This package deliberately does not start a daemon. Starting one is a
+ * distribution/lifecycle concern; a read-only client must not silently create
+ * a second owner while trying to inspect status.
+ */
+export declare function resolveDaemonControlEndpoint(options?: ResolveDaemonControlEndpointOptions): Promise<DaemonControlEndpoint | null>;
+/**
+ * Resolve a live resident daemon without taking ownership of its lifecycle.
+ */
+export declare function ensureDaemonControlEndpoint(options?: ResolveDaemonControlEndpointOptions): Promise<DaemonControlEndpoint>;

package/dist/control-endpoint.js

@@ -0,0 +1,121 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+const PROBE_TIMEOUT_MS = 1_000;
+/**
+ * Read the endpoint published by the App- or supervisor-owned daemon.
+ *
+ * This package deliberately does not start a daemon. Starting one is a
+ * distribution/lifecycle concern; a read-only client must not silently create
+ * a second owner while trying to inspect status.
+ */
+export async function resolveDaemonControlEndpoint(options = {}) {
+    options.signal?.throwIfAborted();
+    const endpoint = await readControlEndpoint();
+    if (!endpoint || !isProcessAlive(endpoint.pid))
+        return null;
+    if (options.probe === false)
+        return endpoint;
+    return await isHealthy(endpoint.origin, options.signal) ? endpoint : null;
+}
+/**
+ * Resolve a live resident daemon without taking ownership of its lifecycle.
+ */
+export async function ensureDaemonControlEndpoint(options = {}) {
+    const endpoint = await resolveDaemonControlEndpoint(options);
+    if (endpoint)
+        return endpoint;
+    throw new Error("Rynx daemon is unavailable; open Rynx App or start the standalone daemon, then retry");
+}
+async function readControlEndpoint() {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(rynxHome(), "control.json"), "utf8"));
+        if (typeof parsed.origin !== "string" ||
+            typeof parsed.pid !== "number" ||
+            !Number.isInteger(parsed.pid) ||
+            parsed.pid <= 0 ||
+            typeof parsed.managementToken !== "string" ||
+            parsed.managementToken.length < 32 ||
+            parsed.managementToken.length > 256) {
+            return null;
+        }
+        const origin = new URL(parsed.origin);
+        if ((origin.protocol !== "http:" && origin.protocol !== "https:") ||
+            origin.username ||
+            origin.password ||
+            origin.search ||
+            origin.hash ||
+            !isLoopbackHostname(origin.hostname)) {
+            return null;
+        }
+        const endpoint = {
+            origin: origin.toString().replace(/\/$/, ""),
+            pid: parsed.pid,
+            managementToken: parsed.managementToken,
+        };
+        if (parsed.distribution === "app" || parsed.distribution === "standalone") {
+            endpoint.distribution = parsed.distribution;
+        }
+        if (boundedMetadata(parsed.productVersion))
+            endpoint.productVersion = parsed.productVersion;
+        if (boundedMetadata(parsed.buildId))
+            endpoint.buildId = parsed.buildId;
+        if (parsed.daemonLifecycle === "follow-app" ||
+            parsed.daemonLifecycle === "resident" ||
+            parsed.daemonLifecycle === "standalone") {
+            endpoint.daemonLifecycle = parsed.daemonLifecycle;
+        }
+        if (validManagementProtocol(parsed.managementProtocol)) {
+            endpoint.managementProtocol = parsed.managementProtocol;
+        }
+        return endpoint;
+    }
+    catch {
+        return null;
+    }
+}
+function validManagementProtocol(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (typeof record.current === "number" &&
+        Number.isInteger(record.current) &&
+        record.current > 0 &&
+        typeof record.minimumCompatible === "number" &&
+        Number.isInteger(record.minimumCompatible) &&
+        record.minimumCompatible > 0 &&
+        record.minimumCompatible <= record.current);
+}
+function boundedMetadata(value) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= 256
+        && value.trim() === value
+        && !/[\u0000-\u001f\u007f]/.test(value);
+}
+async function isHealthy(origin, signal) {
+    try {
+        const response = await fetch(`${origin}/health`, {
+            signal: signal
+                ? AbortSignal.any([signal, AbortSignal.timeout(PROBE_TIMEOUT_MS)])
+                : AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        return response.ok;
+    }
+    catch {
+        signal?.throwIfAborted();
+        return false;
+    }
+}
+function isLoopbackHostname(hostname) {
+    return hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/desktop-browser-host-client.d.ts

@@ -0,0 +1,44 @@
+import { type DesktopBrowserHostCommandFrame, type DesktopBrowserHostErrorCode, type DesktopBrowserHostEvent, type DesktopBrowserHostLeaseFrame, type DesktopBrowserHostPresentation, type DesktopBrowserHostSurfaceCapability, type DesktopBrowserHostSurfaceFrame } from "@rynx-ai/protocol/desktop-browser-host";
+export interface ResidentDesktopBrowserHostConnectOptions {
+    hostInstanceId: string;
+    /** Advertise only handlers that are installed in this main-process Host. */
+    capabilities: {
+        semanticPageBinding: boolean;
+        presentation: DesktopBrowserHostPresentation;
+        surface: DesktopBrowserHostSurfaceCapability;
+    };
+    /**
+     * Process-private endpoint supplied by the daemon that spawned an embedded
+     * Browser Host. It avoids publishing the management credential through argv
+     * or environment variables while the daemon endpoint is still starting.
+     */
+    endpoint?: {
+        origin: string;
+        managementToken: string;
+    };
+    signal?: AbortSignal;
+}
+export interface ResidentDesktopBrowserHostFailure {
+    code: DesktopBrowserHostErrorCode;
+    message: string;
+}
+/**
+ * Process-private lease used by Electron main. The management credential is
+ * resolved and consumed in this package and never returned to the app renderer.
+ */
+export interface ResidentDesktopBrowserHostCommandRequest {
+    readonly frame: DesktopBrowserHostCommandFrame;
+    /** Aborts at the daemon-supplied absolute deadline or on lease loss. */
+    readonly signal: AbortSignal;
+    reply(result: unknown): Promise<void>;
+    reject(failure: ResidentDesktopBrowserHostFailure): Promise<void>;
+}
+export interface ResidentDesktopBrowserHostConnection extends AsyncIterable<ResidentDesktopBrowserHostCommandRequest> {
+    readonly lease: DesktopBrowserHostLeaseFrame;
+    readonly closed: Promise<void>;
+    emit(event: DesktopBrowserHostEvent): Promise<void>;
+    emitSurfaceFrame(frame: Omit<DesktopBrowserHostSurfaceFrame, "leaseId">): Promise<void>;
+    close(): Promise<void>;
+}
+/** Open the sole resident daemon's authenticated loopback Desktop Host lease. */
+export declare function connectResidentDesktopBrowserHost(options: ResidentDesktopBrowserHostConnectOptions): Promise<ResidentDesktopBrowserHostConnection>;

package/dist/desktop-browser-host-client.js

@@ -0,0 +1,430 @@
+import { DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES, DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES, DESKTOP_BROWSER_HOST_MAX_PENDING_COMMANDS, DESKTOP_BROWSER_HOST_PATH, DESKTOP_BROWSER_HOST_PROTOCOL_VERSION, encodeDesktopBrowserHostSurfaceFrame, parseDesktopBrowserHostClientFrame, parseDesktopBrowserHostServerFrame, } from "@rynx-ai/protocol/desktop-browser-host";
+import { WebSocket } from "ws";
+import { ensureDaemonControlEndpoint } from "./control-endpoint.js";
+const CONNECT_TIMEOUT_MS = 5_000;
+const MAX_BUFFERED_BYTES = DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES + DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES;
+/** Open the sole resident daemon's authenticated loopback Desktop Host lease. */
+export async function connectResidentDesktopBrowserHost(options) {
+    options.signal?.throwIfAborted();
+    const hello = parseDesktopBrowserHostClientFrame({
+        type: "desktop.browser.host.hello",
+        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+        hostInstanceId: options.hostInstanceId,
+        capabilities: {
+            semanticPageBinding: options.capabilities.semanticPageBinding,
+            presentation: options.capabilities.presentation,
+            surface: options.capabilities.surface,
+        },
+    });
+    if (hello.type !== "desktop.browser.host.hello") {
+        throw new Error("Desktop Browser Host hello parser returned the wrong frame");
+    }
+    const endpoint = options.endpoint
+        ?? await ensureDaemonControlEndpoint({ signal: options.signal });
+    assertDesktopBrowserHostEndpoint(endpoint);
+    const url = new URL(DESKTOP_BROWSER_HOST_PATH, `${endpoint.origin}/`);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    const socket = new WebSocket(url, {
+        headers: { "x-rynx-management-token": endpoint.managementToken },
+        handshakeTimeout: CONNECT_TIMEOUT_MS,
+        maxPayload: DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES,
+        perMessageDeflate: false,
+    });
+    const queue = new BoundedCommandQueue(DESKTOP_BROWSER_HOST_MAX_PENDING_COMMANDS);
+    let lease;
+    let leaseResolve;
+    let leaseReject;
+    const leaseReady = new Promise((resolve, reject) => {
+        leaseResolve = resolve;
+        leaseReject = reject;
+    });
+    let closedResolve;
+    const closed = new Promise((resolve) => {
+        closedResolve = resolve;
+    });
+    let terminalError;
+    let eventSequence = 0;
+    let closing = false;
+    let writerTail = Promise.resolve();
+    const activeRequests = new Map();
+    const abortActiveRequests = (error) => {
+        for (const request of activeRequests.values()) {
+            if (request.timer)
+                clearTimeout(request.timer);
+            request.settled = true;
+            request.controller.abort(error);
+        }
+        activeRequests.clear();
+    };
+    const fail = (error) => {
+        terminalError ??= error;
+        if (!lease)
+            leaseReject(error);
+        queue.close(error);
+        abortActiveRequests(error);
+    };
+    const failConnection = (error, code, reason) => {
+        fail(error);
+        if (socket.readyState < WebSocket.CLOSING)
+            socket.close(code, reason);
+    };
+    const enqueueWrite = (operation) => {
+        const current = writerTail.then(async () => {
+            if (terminalError)
+                throw terminalError;
+            await operation();
+        });
+        writerTail = current.catch(() => undefined);
+        return current.catch((error) => {
+            const failure = asError(error, "Desktop Browser Host output failed");
+            failConnection(failure, 1011, "host output failed");
+            throw failure;
+        });
+    };
+    const onAbort = () => {
+        const error = abortError(options.signal?.reason);
+        failConnection(error, 1000, "aborted");
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    socket.on("open", () => {
+        void enqueueWrite(() => sendJson(socket, hello));
+    });
+    socket.on("message", (raw, isBinary) => {
+        if (isBinary) {
+            failConnection(new Error("Desktop Browser Host daemon sent an unexpected binary frame"), 1003, "binary frame unsupported");
+            return;
+        }
+        let frame;
+        try {
+            const bytes = rawDataBytes(raw);
+            if (bytes.byteLength === 0 || bytes.byteLength > DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES) {
+                throw new Error("Desktop Browser Host daemon frame exceeded its bound");
+            }
+            frame = parseDesktopBrowserHostServerFrame(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+        }
+        catch (error) {
+            failConnection(asError(error, "Desktop Browser Host daemon frame was invalid"), 1007, "invalid daemon frame");
+            return;
+        }
+        if (!lease) {
+            if (frame.type !== "desktop.browser.host.lease") {
+                failConnection(new Error("Desktop Browser Host daemon did not begin with a lease"), 1002, "lease required");
+                return;
+            }
+            if (frame.capabilities.semanticPageBinding &&
+                !options.capabilities.semanticPageBinding) {
+                failConnection(new Error("Desktop Browser Host daemon enabled an unadvertised Page binding capability"), 1002, "invalid lease capabilities");
+                return;
+            }
+            if (frame.capabilities.surface === "binary-v1" &&
+                options.capabilities.surface !== "binary-v1") {
+                failConnection(new Error("Desktop Browser Host daemon enabled an unadvertised Surface capability"), 1002, "invalid lease capabilities");
+                return;
+            }
+            lease = frame;
+            leaseResolve(frame);
+            return;
+        }
+        if (frame.type !== "desktop.browser.host.command" || frame.leaseId !== lease.leaseId) {
+            failConnection(new Error("Desktop Browser Host daemon sent a frame outside the active lease"), 1002, "lease mismatch");
+            return;
+        }
+        if (!queue.push(frame)) {
+            failConnection(new Error("Desktop Browser Host command capacity exceeded"), 1013, "command capacity exceeded");
+        }
+    });
+    socket.on("error", (error) => {
+        failConnection(new Error("Desktop Browser Host connection failed", { cause: error }), 1011, "connection failed");
+    });
+    socket.once("close", (code, reason) => {
+        options.signal?.removeEventListener("abort", onAbort);
+        if (!terminalError && !closing) {
+            terminalError = new Error(`Desktop Browser Host lease closed (${code})${reason.length > 0 ? `: ${reason.toString("utf8")}` : ""}`);
+        }
+        if (!lease && terminalError)
+            leaseReject(terminalError);
+        queue.close(terminalError);
+        abortActiveRequests(terminalError ?? new Error("Desktop Browser Host lease closed"));
+        closedResolve();
+    });
+    try {
+        lease = await abortableTimeout(leaseReady, CONNECT_TIMEOUT_MS, options.signal);
+    }
+    catch (error) {
+        if (socket.readyState < WebSocket.CLOSING)
+            socket.close(1000, "lease failed");
+        throw error;
+    }
+    const activeLease = lease;
+    const settle = async (command, value) => {
+        const request = activeRequests.get(command.commandId);
+        if (!request || request.settled) {
+            throw new Error("Desktop Browser Host command is already settled or stale");
+        }
+        if (command.leaseId !== activeLease.leaseId ||
+            request.controller.signal.aborted ||
+            Date.now() >= command.deadlineUnixMilliseconds) {
+            expireRequest(command, request);
+            throw new Error("Desktop Browser Host command deadline expired before settlement");
+        }
+        request.settled = true;
+        if (request.timer)
+            clearTimeout(request.timer);
+        activeRequests.delete(command.commandId);
+        await enqueueWrite(async () => {
+            const frame = parseDesktopBrowserHostClientFrame(value);
+            if (frame.type !== "desktop.browser.host.reply") {
+                throw new Error("Desktop Browser Host reply parser returned the wrong frame");
+            }
+            await sendJson(socket, frame);
+        });
+    };
+    const expireRequest = (command, request) => {
+        if (request.settled)
+            return;
+        request.settled = true;
+        if (request.timer)
+            clearTimeout(request.timer);
+        activeRequests.delete(command.commandId);
+        const error = new Error(`Desktop Browser Host ${command.command.method} deadline expired`);
+        request.controller.abort(error);
+        if (isMutatingCommand(command)) {
+            failConnection(error, 1000, "command deadline expired");
+        }
+    };
+    const requestIterator = queue[Symbol.asyncIterator]();
+    const claimedIterator = {
+        next: async () => {
+            const next = await requestIterator.next();
+            if (next.done)
+                return { done: true, value: undefined };
+            const command = next.value;
+            if (activeRequests.has(command.commandId)) {
+                const error = new Error("Desktop Browser Host daemon repeated a commandId");
+                failConnection(error, 1002, "duplicate command");
+                throw error;
+            }
+            const controller = new AbortController();
+            const remaining = command.deadlineUnixMilliseconds - Date.now();
+            const request = {
+                controller,
+                settled: false,
+            };
+            request.timer = setTimeout(() => expireRequest(command, request), Math.max(1, remaining));
+            request.timer.unref?.();
+            activeRequests.set(command.commandId, request);
+            if (remaining <= 0) {
+                expireRequest(command, request);
+                throw new Error("Desktop Browser Host received an expired command");
+            }
+            return {
+                done: false,
+                value: {
+                    frame: command,
+                    signal: controller.signal,
+                    reply: (result) => settle(command, {
+                        type: "desktop.browser.host.reply",
+                        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                        leaseId: activeLease.leaseId,
+                        commandId: command.commandId,
+                        ok: true,
+                        result,
+                    }),
+                    reject: (failure) => settle(command, {
+                        type: "desktop.browser.host.reply",
+                        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                        leaseId: activeLease.leaseId,
+                        commandId: command.commandId,
+                        ok: false,
+                        error: failure,
+                    }),
+                },
+            };
+        },
+    };
+    return {
+        lease: activeLease,
+        closed,
+        [Symbol.asyncIterator]: () => claimedIterator,
+        emit: (event) => enqueueWrite(async () => {
+            const nextSequence = eventSequence + 1;
+            const frame = parseDesktopBrowserHostClientFrame({
+                type: "desktop.browser.host.event",
+                protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                leaseId: activeLease.leaseId,
+                eventSequence: nextSequence,
+                event,
+            });
+            if (frame.type !== "desktop.browser.host.event") {
+                throw new Error("Desktop Browser Host event parser returned the wrong frame");
+            }
+            await sendJson(socket, frame);
+            eventSequence = nextSequence;
+        }),
+        emitSurfaceFrame: (frame) => enqueueWrite(async () => {
+            if (activeLease.capabilities.surface !== "binary-v1") {
+                throw new Error("Desktop Browser Host Surface was not negotiated");
+            }
+            const encoded = encodeDesktopBrowserHostSurfaceFrame({
+                ...frame,
+                leaseId: activeLease.leaseId,
+            });
+            await sendBinary(socket, encoded);
+        }),
+        close: async () => {
+            if (closing)
+                return closed;
+            closing = true;
+            queue.close();
+            abortActiveRequests(new Error("Desktop Browser Host stopped"));
+            if (socket.readyState < WebSocket.CLOSING)
+                socket.close(1000, "host stopped");
+            if (socket.readyState === WebSocket.CLOSED)
+                closedResolve();
+            await closed;
+        },
+    };
+}
+async function sendBinary(socket, bytes) {
+    if (socket.readyState !== WebSocket.OPEN)
+        throw new Error("Desktop Browser Host lease is closed");
+    if (bytes.byteLength === 0 || bytes.byteLength > DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES) {
+        throw new Error("Desktop Browser Host binary frame exceeded its bound");
+    }
+    if (socket.bufferedAmount + bytes.byteLength > MAX_BUFFERED_BYTES) {
+        throw new Error("Desktop Browser Host output buffer exceeded its bound");
+    }
+    await new Promise((resolve, reject) => {
+        socket.send(bytes, { binary: true, compress: false }, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+async function sendJson(socket, value) {
+    if (socket.readyState !== WebSocket.OPEN)
+        throw new Error("Desktop Browser Host lease is closed");
+    const bytes = Buffer.from(JSON.stringify(value), "utf8");
+    if (bytes.byteLength === 0 || bytes.byteLength > DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES) {
+        throw new Error("Desktop Browser Host client frame exceeded its bound");
+    }
+    if (socket.bufferedAmount + bytes.byteLength > MAX_BUFFERED_BYTES) {
+        throw new Error("Desktop Browser Host output buffer exceeded its bound");
+    }
+    await new Promise((resolve, reject) => {
+        socket.send(bytes, { binary: false, compress: false }, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+class BoundedCommandQueue {
+    capacity;
+    values = [];
+    waiters = [];
+    ended = false;
+    error;
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
+    push(value) {
+        if (this.ended)
+            return false;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ done: false, value });
+            return true;
+        }
+        if (this.values.length >= this.capacity)
+            return false;
+        this.values.push(value);
+        return true;
+    }
+    close(error) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.error = error;
+        // Commands are capabilities of this exact socket lease. Never drain a
+        // buffered command after abort/disconnect, even if it was parsed earlier.
+        this.values.length = 0;
+        for (const waiter of this.waiters.splice(0)) {
+            if (error)
+                waiter.reject(error);
+            else
+                waiter.resolve({ done: true, value: undefined });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const value = this.values.shift();
+                if (value)
+                    return Promise.resolve({ done: false, value });
+                if (this.ended) {
+                    return this.error
+                        ? Promise.reject(this.error)
+                        : Promise.resolve({ done: true, value: undefined });
+                }
+                return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+            },
+        };
+    }
+}
+function rawDataBytes(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (Array.isArray(data))
+        return Buffer.concat(data);
+    throw new Error("Desktop Browser Host received an unsupported WebSocket payload");
+}
+function isMutatingCommand(command) {
+    return command.command.method !== "browser.snapshot" &&
+        command.command.method !== "browser.cdp-endpoint" &&
+        command.command.method !== "page.cdp-endpoint";
+}
+async function abortableTimeout(promise, timeoutMs, signal) {
+    signal?.throwIfAborted();
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    return await new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(combined.reason));
+        combined.addEventListener("abort", onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => combined.removeEventListener("abort", onAbort));
+    });
+}
+function abortError(reason) {
+    if (reason instanceof Error)
+        return reason;
+    return new Error("Desktop Browser Host connection was aborted", { cause: reason });
+}
+function asError(error, message) {
+    return error instanceof Error ? error : new Error(message, { cause: error });
+}
+function assertDesktopBrowserHostEndpoint(endpoint) {
+    if (endpoint.managementToken.length < 32 ||
+        endpoint.managementToken.length > 256 ||
+        endpoint.managementToken.trim() !== endpoint.managementToken ||
+        /[\u0000-\u001f\u007f]/.test(endpoint.managementToken)) {
+        throw new Error("resident daemon Desktop Browser Host credential is invalid");
+    }
+    const origin = endpoint.origin;
+    const url = new URL(origin);
+    const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if ((url.protocol !== "http:" && url.protocol !== "https:") ||
+        url.username ||
+        url.password ||
+        url.pathname !== "/" ||
+        url.search ||
+        url.hash ||
+        url.origin !== origin ||
+        (host !== "localhost" && host !== "127.0.0.1" && host !== "::1")) {
+        throw new Error("resident daemon Desktop Browser Host endpoint is not loopback");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { runCli } from "./run-cli.js";
+export { USAGE } from "./usage.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { runCli } from "./run-cli.js";
+export { USAGE } from "./usage.js";

package/dist/legacy-adapter.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Temporary bridge for commands whose daemon-owned mutation has no management
+ * RPC yet. It crosses the package boundary as a subprocess, never by importing
+ * daemon implementation modules into the CLI process.
+ */
+export declare function runLegacyDaemonCli(args: readonly string[]): Promise<number>;
+export declare function resolveLegacyDaemonCli(env?: NodeJS.ProcessEnv, moduleUrl?: string): string | null;