@rynx-ai/daemon 0.1.9 → 0.1.10-beta.2

package/dist/chrome-inspection-manager.d.ts

@@ -0,0 +1,94 @@
+import { type RuntimeBrowserInspectMessage, type RuntimeBrowserInspectTarget } from "@rynx-ai/protocol/runtime-browser-inspect";
+import type { RuntimeConnectionLease, SessionBrowserService } from "@rynx-ai/server";
+import { type ChromeInspectionGateway, type StartChromeInspectionGatewayOptions } from "./chrome-inspection-gateway.js";
+export interface ChromeInspectionSettings {
+    enabled: boolean;
+    includeLocal: boolean;
+    remoteDaemonIds: string[];
+}
+export interface ChromeInspectionStatus {
+    settings: ChromeInspectionSettings;
+    runtime: {
+        state: "disabled" | "listening" | "error";
+        address: string;
+        error?: string;
+    };
+    remotes: Array<{
+        daemonId: string;
+        displayName: string;
+        selected: boolean;
+        status: "ready" | "offline" | "incompatible";
+    }>;
+}
+export interface ChromeInspectionRemoteTarget {
+    daemonId: string;
+    displayName: string;
+    createdAt: string;
+}
+interface RemoteInspectConnection extends AsyncIterable<RuntimeBrowserInspectMessage> {
+    readonly daemonInstanceId: string;
+    send(message: RuntimeBrowserInspectMessage): Promise<void>;
+    close(): Promise<void>;
+}
+interface InspectionRuntimeLease extends RuntimeConnectionLease {
+    openBrowserInspect(target: RuntimeBrowserInspectTarget, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<RemoteInspectConnection>;
+}
+export interface ChromeInspectionRuntimeConnections {
+    acquire(selector: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<InspectionRuntimeLease>;
+}
+export interface ChromeInspectionManagerOptions {
+    localDaemonInstanceId: string;
+    browsers: Pick<SessionBrowserService, "listInspectionTargets" | "getInspectionPageEndpoint" | "activatePage" | "closePage">;
+    runtimeTargets: {
+        list(): ChromeInspectionRemoteTarget[];
+    };
+    runtimeConnections: ChromeInspectionRuntimeConnections;
+    configFile?: string;
+    port?: number;
+    startGateway?: (options: StartChromeInspectionGatewayOptions) => Promise<ChromeInspectionGateway>;
+    onError?: (error: Error, context: string) => void;
+}
+/**
+ * Daemon-owned desired state and target source for Chrome inspection.
+ *
+ * The App can disappear without affecting this object. Reopening the App only
+ * reads its status; it never moves or recreates Browser attachments.
+ */
+export declare class ChromeInspectionManager {
+    private readonly options;
+    private settings;
+    private gateway?;
+    private runtimeError?;
+    private routes;
+    private remoteCache;
+    private remoteInflight;
+    private operation;
+    private stopped;
+    private constructor();
+    static create(options: ChromeInspectionManagerOptions): Promise<ChromeInspectionManager>;
+    status(): Promise<ChromeInspectionStatus>;
+    configure(input: ChromeInspectionSettings): Promise<ChromeInspectionStatus>;
+    shutdown(): Promise<void>;
+    private source;
+    private listTargets;
+    private resolveLocalEndpoint;
+    private openRemoteConnection;
+    private mutatePage;
+    private remoteInventory;
+    private loadRemoteInventory;
+    private probeRemote;
+    private sanitizeSelections;
+    private currentRemoteTargets;
+    private isRemoteSelected;
+    private publicSettings;
+    private reconcileGateway;
+    private serial;
+    private assertRunning;
+    private configFile;
+}
+export {};

package/dist/chrome-inspection-manager.js

@@ -0,0 +1,573 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+import { RUNTIME_BROWSER_INSPECT_SEMANTIC_CAPABILITY, } from "@rynx-ai/protocol/runtime-browser-inspect";
+import { startChromeInspectionGateway, } from "./chrome-inspection-gateway.js";
+const CONFIG_SCHEMA_VERSION = 1;
+const DEFAULT_PORT = 9_333;
+const REMOTE_CALL_TIMEOUT_MS = 3_000;
+const REMOTE_DISCOVERY_CACHE_MS = 2_000;
+const MAX_REMOTE_RUNTIMES = 64;
+const MAX_REMOTE_SESSIONS = 256;
+const SESSION_PAGE_SIZE = 100;
+const OPAQUE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}$/;
+/**
+ * Daemon-owned desired state and target source for Chrome inspection.
+ *
+ * The App can disappear without affecting this object. Reopening the App only
+ * reads its status; it never moves or recreates Browser attachments.
+ */
+export class ChromeInspectionManager {
+    options;
+    settings = defaultPersistedSettings();
+    gateway;
+    runtimeError;
+    routes = new Map();
+    remoteCache = new Map();
+    remoteInflight = new Map();
+    operation = Promise.resolve();
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+    }
+    static async create(options) {
+        const manager = new ChromeInspectionManager(options);
+        try {
+            manager.settings = await loadSettings(manager.configFile());
+        }
+        catch (error) {
+            // Corrupt local settings must fail closed without preventing the daemon
+            // from starting. The next explicit configure operation rewrites them.
+            manager.settings = defaultPersistedSettings();
+            options.onError?.(asError(error), "settings load");
+        }
+        manager.sanitizeSelections();
+        await manager.reconcileGateway();
+        return manager;
+    }
+    async status() {
+        this.sanitizeSelections();
+        const selected = new Set(this.settings.remotes.map((entry) => entry.daemonId));
+        const remoteTargets = this.currentRemoteTargets();
+        const probes = await Promise.all(remoteTargets.map(async (target) => ({
+            target,
+            status: await this.probeRemote(target.daemonId),
+        })));
+        return {
+            settings: this.publicSettings(),
+            runtime: {
+                state: !this.settings.enabled
+                    ? "disabled"
+                    : this.gateway
+                        ? "listening"
+                        : "error",
+                address: `127.0.0.1:${this.options.port ?? DEFAULT_PORT}`,
+                ...(this.runtimeError ? { error: this.runtimeError } : {}),
+            },
+            remotes: probes.map(({ target, status }) => ({
+                daemonId: target.daemonId,
+                displayName: target.displayName,
+                selected: selected.has(target.daemonId),
+                status,
+            })),
+        };
+    }
+    configure(input) {
+        return this.serial(async () => {
+            this.assertRunning();
+            const normalized = normalizePublicSettings(input);
+            const targets = new Map(this.currentRemoteTargets().map((target) => [target.daemonId, target]));
+            const remotes = normalized.remoteDaemonIds.map((daemonId) => {
+                const target = targets.get(daemonId);
+                if (!target) {
+                    throw new Error(`Remote Runtime ${daemonId} is not paired on this device`);
+                }
+                return {
+                    daemonId,
+                    targetCreatedAt: target.createdAt,
+                };
+            });
+            const nextSettings = {
+                schemaVersion: CONFIG_SCHEMA_VERSION,
+                enabled: normalized.enabled,
+                includeLocal: normalized.includeLocal,
+                remotes,
+            };
+            await persistSettings(this.configFile(), nextSettings);
+            this.settings = nextSettings;
+            this.remoteCache.clear();
+            await this.reconcileGateway();
+            return await this.status();
+        });
+    }
+    shutdown() {
+        return this.serial(async () => {
+            if (this.stopped)
+                return;
+            this.stopped = true;
+            const gateway = this.gateway;
+            this.gateway = undefined;
+            if (gateway)
+                await gateway.shutdown();
+            this.routes.clear();
+            this.remoteCache.clear();
+        });
+    }
+    source() {
+        return {
+            listTargets: () => this.listTargets(),
+            resolveWebSocketEndpoint: (target) => this.resolveLocalEndpoint(target),
+            openConnection: (target, options) => this.openRemoteConnection(target, options),
+            activate: (target) => this.mutatePage(target, "activate"),
+            close: (target) => this.mutatePage(target, "close"),
+        };
+    }
+    async listTargets() {
+        this.assertRunning();
+        this.sanitizeSelections();
+        const nextRoutes = new Map();
+        const targets = [];
+        if (this.settings.includeLocal) {
+            for (const target of this.options.browsers.listInspectionTargets()) {
+                const key = localTargetKey(this.options.localDaemonInstanceId, target);
+                nextRoutes.set(key, {
+                    kind: "local",
+                    sessionId: target.sessionId,
+                    browserGeneration: target.browserGeneration,
+                    pageId: target.pageId,
+                });
+                targets.push(projectTarget(key, target, `This device · ${target.executionBackend}`));
+            }
+        }
+        const remoteTargets = new Map(this.currentRemoteTargets().map((target) => [target.daemonId, target]));
+        const selected = this.settings.remotes
+            .map((entry) => remoteTargets.get(entry.daemonId))
+            .filter((entry) => Boolean(entry));
+        const inventories = await Promise.all(selected.map((target) => this.remoteInventory(target).catch((error) => {
+            this.options.onError?.(asError(error), `remote discovery ${target.daemonId}`);
+            const stale = this.remoteCache.get(target.daemonId);
+            if (!stale)
+                return undefined;
+            const retained = {
+                ...stale,
+                expiresAt: Date.now() + REMOTE_DISCOVERY_CACHE_MS,
+            };
+            this.remoteCache.set(target.daemonId, retained);
+            return retained;
+        })));
+        for (const inventory of inventories) {
+            if (!inventory)
+                continue;
+            targets.push(...inventory.targets);
+            for (const [key, route] of inventory.routes)
+                nextRoutes.set(key, route);
+        }
+        this.routes = nextRoutes;
+        return targets;
+    }
+    async resolveLocalEndpoint(target) {
+        const route = this.routes.get(target.key);
+        if (!route || route.kind !== "local") {
+            throw new Error("Chrome inspection target is not a current local Page");
+        }
+        const endpoint = await this.options.browsers.getInspectionPageEndpoint({
+            sessionId: route.sessionId,
+            browserGeneration: route.browserGeneration,
+            pageId: route.pageId,
+        });
+        return endpoint.endpoint;
+    }
+    async openRemoteConnection(target, options = {}) {
+        const route = this.routes.get(target.key);
+        if (!route || route.kind === "local")
+            return undefined;
+        if (!this.isRemoteSelected(route.daemonId)) {
+            throw new Error("Remote Runtime is no longer selected for inspection");
+        }
+        const lease = await this.options.runtimeConnections.acquire(route.daemonId, {
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        try {
+            const connection = await lease.openBrowserInspect({
+                sessionId: route.sessionId,
+                browserGeneration: route.browserGeneration,
+                pageId: route.pageId,
+            }, {
+                ...(options.signal ? { signal: options.signal } : {}),
+                timeoutMs: REMOTE_CALL_TIMEOUT_MS,
+            });
+            if (connection.daemonInstanceId !== route.daemonInstanceId) {
+                await connection.close().catch(() => undefined);
+                throw new Error("Remote Runtime restarted after target discovery");
+            }
+            return leasedConnection(connection, lease);
+        }
+        catch (error) {
+            lease.release();
+            throw error;
+        }
+    }
+    async mutatePage(target, action) {
+        const route = this.routes.get(target.key);
+        if (!route)
+            throw new Error("Chrome inspection target is stale");
+        const params = {
+            sessionId: route.sessionId,
+            browserGeneration: route.browserGeneration,
+            pageId: route.pageId,
+        };
+        if (route.kind === "local") {
+            if (action === "activate")
+                await this.options.browsers.activatePage(params);
+            else
+                await this.options.browsers.closePage(params);
+            return;
+        }
+        if (!this.isRemoteSelected(route.daemonId)) {
+            throw new Error("Remote Runtime is no longer selected for inspection");
+        }
+        const lease = await this.options.runtimeConnections.acquire(route.daemonId);
+        try {
+            await lease.call(action === "activate" ? "browser.page.activate" : "browser.page.close", params, { timeoutMs: REMOTE_CALL_TIMEOUT_MS });
+        }
+        finally {
+            lease.release();
+        }
+    }
+    async remoteInventory(target) {
+        const cached = this.remoteCache.get(target.daemonId);
+        if (cached && cached.expiresAt > Date.now())
+            return cached;
+        const existing = this.remoteInflight.get(target.daemonId);
+        if (existing)
+            return existing;
+        const loading = this.loadRemoteInventory(target).finally(() => {
+            this.remoteInflight.delete(target.daemonId);
+        });
+        this.remoteInflight.set(target.daemonId, loading);
+        const loaded = await loading;
+        this.remoteCache.set(target.daemonId, loaded);
+        return loaded;
+    }
+    async loadRemoteInventory(target) {
+        const lease = await this.options.runtimeConnections.acquire(target.daemonId);
+        try {
+            const status = await lease.call("status.get", {}, {
+                timeoutMs: REMOTE_CALL_TIMEOUT_MS,
+            });
+            if (!status.semanticCapabilities.includes(RUNTIME_BROWSER_INSPECT_SEMANTIC_CAPABILITY)) {
+                throw new Error("Remote Runtime does not support Browser inspection");
+            }
+            const sessions = await listRemoteSessions(lease);
+            const states = await mapLimit(sessions, 8, async (sessionId) => lease.call("browser.state.get", { sessionId }, {
+                timeoutMs: REMOTE_CALL_TIMEOUT_MS,
+            }));
+            const targets = [];
+            const routes = new Map();
+            for (const state of states) {
+                if (!state || state.status !== "ready")
+                    continue;
+                for (const page of state.pages) {
+                    const key = remoteTargetKey(target.daemonId, status.daemonInstanceId, state.sessionId, state.browserGeneration, page.pageId);
+                    routes.set(key, {
+                        kind: "remote",
+                        daemonId: target.daemonId,
+                        daemonInstanceId: status.daemonInstanceId,
+                        sessionId: state.sessionId,
+                        browserGeneration: state.browserGeneration,
+                        pageId: page.pageId,
+                    });
+                    targets.push(projectTarget(key, {
+                        sessionId: state.sessionId,
+                        browserGeneration: state.browserGeneration,
+                        pageId: page.pageId,
+                        executionBackend: state.executionBackend,
+                        title: page.title,
+                        url: page.url,
+                    }, `${target.displayName} · ${state.executionBackend}`));
+                }
+            }
+            return {
+                expiresAt: Date.now() + REMOTE_DISCOVERY_CACHE_MS,
+                targets,
+                routes,
+            };
+        }
+        finally {
+            lease.release();
+        }
+    }
+    async probeRemote(daemonId) {
+        let lease;
+        try {
+            lease = await this.options.runtimeConnections.acquire(daemonId, {
+                signal: AbortSignal.timeout(REMOTE_CALL_TIMEOUT_MS),
+            });
+            const status = await lease.call("status.get", {}, {
+                timeoutMs: REMOTE_CALL_TIMEOUT_MS,
+            });
+            return status.semanticCapabilities.includes(RUNTIME_BROWSER_INSPECT_SEMANTIC_CAPABILITY)
+                ? "ready"
+                : "incompatible";
+        }
+        catch {
+            return "offline";
+        }
+        finally {
+            lease?.release();
+        }
+    }
+    sanitizeSelections() {
+        const current = new Map(this.currentRemoteTargets().map((target) => [target.daemonId, target]));
+        this.settings.remotes = this.settings.remotes.filter((selected) => {
+            const target = current.get(selected.daemonId);
+            return target?.createdAt === selected.targetCreatedAt;
+        });
+    }
+    currentRemoteTargets() {
+        return this.options.runtimeTargets.list().slice(0, MAX_REMOTE_RUNTIMES);
+    }
+    isRemoteSelected(daemonId) {
+        return this.settings.remotes.some((entry) => entry.daemonId === daemonId);
+    }
+    publicSettings() {
+        return {
+            enabled: this.settings.enabled,
+            includeLocal: this.settings.includeLocal,
+            remoteDaemonIds: this.settings.remotes.map((entry) => entry.daemonId),
+        };
+    }
+    async reconcileGateway() {
+        const existing = this.gateway;
+        this.gateway = undefined;
+        if (existing)
+            await existing.shutdown();
+        this.routes.clear();
+        this.runtimeError = undefined;
+        if (!this.settings.enabled || this.stopped)
+            return;
+        try {
+            this.gateway = await (this.options.startGateway ?? startChromeInspectionGateway)({
+                source: this.source(),
+                port: this.options.port ?? DEFAULT_PORT,
+                onError: this.options.onError,
+            });
+        }
+        catch (error) {
+            const normalized = asError(error);
+            this.runtimeError = hasCode(normalized, "EADDRINUSE")
+                ? "Port 9333 is already in use."
+                : normalized.message;
+            this.options.onError?.(normalized, "gateway startup");
+        }
+    }
+    serial(operation) {
+        const run = this.operation.then(operation, operation);
+        this.operation = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    assertRunning() {
+        if (this.stopped)
+            throw new Error("Chrome inspection manager is stopped");
+    }
+    configFile() {
+        return this.options.configFile ??
+            join(rynxHome(), "chrome-inspection.json");
+    }
+}
+function projectTarget(key, target, description) {
+    return {
+        key,
+        title: target.title || "(untitled)",
+        url: target.url,
+        description,
+        // Discovery does not wake or reconcile a Browser just to read its version.
+        // The exact engine endpoint remains attach-time-only.
+        engineVersion: "Chrome/0.0.0.0",
+    };
+}
+function localTargetKey(daemonInstanceId, target) {
+    return [
+        "local",
+        daemonInstanceId,
+        target.sessionId,
+        target.browserGeneration,
+        target.pageId,
+    ].join(":");
+}
+function remoteTargetKey(daemonId, daemonInstanceId, sessionId, generation, pageId) {
+    return [
+        "remote",
+        daemonId,
+        daemonInstanceId,
+        sessionId,
+        generation,
+        pageId,
+    ].join(":");
+}
+function leasedConnection(connection, lease) {
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        try {
+            await connection.close();
+        }
+        finally {
+            lease.release();
+        }
+    };
+    return {
+        send: (message) => connection.send(message),
+        close,
+        async *[Symbol.asyncIterator]() {
+            try {
+                for await (const message of connection)
+                    yield message;
+            }
+            finally {
+                await close();
+            }
+        },
+    };
+}
+async function listRemoteSessions(lease) {
+    const sessions = [];
+    let cursor;
+    while (sessions.length < MAX_REMOTE_SESSIONS) {
+        const result = await lease.call("session.list", {
+            limit: SESSION_PAGE_SIZE,
+            ...(cursor ? { cursor } : {}),
+        }, {
+            timeoutMs: REMOTE_CALL_TIMEOUT_MS,
+        });
+        sessions.push(...result.sessions.map((session) => session.id));
+        if (!result.hasMore || !result.nextCursor)
+            break;
+        cursor = result.nextCursor;
+    }
+    return sessions.slice(0, MAX_REMOTE_SESSIONS);
+}
+async function mapLimit(values, concurrency, mapper) {
+    const result = new Array(values.length);
+    let index = 0;
+    const workers = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+        while (index < values.length) {
+            const current = index;
+            index += 1;
+            result[current] = await mapper(values[current]);
+        }
+    });
+    await Promise.all(workers);
+    return result;
+}
+function normalizePublicSettings(input) {
+    if (!input ||
+        typeof input !== "object" ||
+        typeof input.enabled !== "boolean" ||
+        typeof input.includeLocal !== "boolean" ||
+        !Array.isArray(input.remoteDaemonIds)) {
+        throw new TypeError("Chrome inspection settings are invalid");
+    }
+    const remoteDaemonIds = input.remoteDaemonIds.map((value) => {
+        if (typeof value !== "string" || !OPAQUE_ID_PATTERN.test(value)) {
+            throw new TypeError("Chrome inspection Remote Runtime id is invalid");
+        }
+        return value;
+    });
+    if (remoteDaemonIds.length > MAX_REMOTE_RUNTIMES ||
+        new Set(remoteDaemonIds).size !== remoteDaemonIds.length) {
+        throw new TypeError("Chrome inspection Remote Runtime selection is invalid");
+    }
+    return {
+        enabled: input.enabled,
+        includeLocal: input.includeLocal,
+        remoteDaemonIds,
+    };
+}
+async function loadSettings(file) {
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (hasCode(error, "ENOENT"))
+            return defaultPersistedSettings();
+        throw error;
+    }
+    if (Buffer.byteLength(raw, "utf8") > 64 * 1024) {
+        throw new Error("Chrome inspection settings file is too large");
+    }
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Chrome inspection settings file is invalid");
+    }
+    const record = value;
+    if (record.schemaVersion !== CONFIG_SCHEMA_VERSION ||
+        typeof record.enabled !== "boolean" ||
+        typeof record.includeLocal !== "boolean" ||
+        !Array.isArray(record.remotes) ||
+        record.remotes.length > MAX_REMOTE_RUNTIMES) {
+        throw new Error("Chrome inspection settings file is invalid");
+    }
+    const remotes = record.remotes.map((value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error("Chrome inspection settings file is invalid");
+        }
+        const remote = value;
+        if (Object.keys(remote).sort().join(",") !== "daemonId,targetCreatedAt" ||
+            typeof remote.daemonId !== "string" ||
+            !OPAQUE_ID_PATTERN.test(remote.daemonId) ||
+            typeof remote.targetCreatedAt !== "string" ||
+            !Number.isFinite(Date.parse(remote.targetCreatedAt))) {
+            throw new Error("Chrome inspection settings file is invalid");
+        }
+        return {
+            daemonId: remote.daemonId,
+            targetCreatedAt: remote.targetCreatedAt,
+        };
+    });
+    if (new Set(remotes.map((remote) => remote.daemonId)).size !== remotes.length) {
+        throw new Error("Chrome inspection settings file contains duplicate Runtime ids");
+    }
+    return {
+        schemaVersion: CONFIG_SCHEMA_VERSION,
+        enabled: record.enabled,
+        includeLocal: record.includeLocal,
+        remotes,
+    };
+}
+async function persistSettings(file, settings) {
+    const directory = dirname(file);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = join(directory, `.chrome-inspection.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+    try {
+        await writeFile(temporary, `${JSON.stringify(settings, null, 2)}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+function defaultPersistedSettings() {
+    return {
+        schemaVersion: CONFIG_SCHEMA_VERSION,
+        enabled: false,
+        includeLocal: true,
+        remotes: [],
+    };
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function hasCode(error, code) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}