@rynx-ai/cli 0.1.11-beta.5 → 0.1.11-beta.51

package/dist/commands/setup.js

@@ -3,10 +3,15 @@ import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, re
 import path from "node:path";
 import * as prompts from "@clack/prompts";
 import { AGENT_RUNTIME_IDS, getRuntimeProfile, loadConfig, rynxConfigFile, } from "@rynx-ai/core";
-import { inspectDaemonDiagnostics, prepareBundledPlugins, } from "@rynx-ai/daemon/setup-service";
+import { inspectDaemonDiagnostics, inspectSystemDependencies, prepareBundledPlugins, } from "@rynx-ai/daemon/setup-service";
+import { BUNDLED_TMUX_UNAVAILABLE_MESSAGE, resolveBundledTmux, } from "@rynx-ai/tmux";
+import { enableAutostart, inspectAutostart, } from "../autostart.js";
+import { createProgressDisplay } from "../progress-display.js";
 import { fail } from "./errors.js";
+import { runLifecycleCommand } from "./lifecycle.js";
 export async function runSetupCommand(args) {
     const options = parseSetupOptions(args);
+    const progress = options.json ? undefined : createProgressDisplay();
     const interactive = !options.nonInteractive &&
         !options.hasConfigurationArguments &&
         Boolean(process.stdin.isTTY && process.stdout.isTTY);
@@ -50,23 +55,30 @@ export async function runSetupCommand(args) {
         },
     };
     let failed = false;
+    progress?.start("正在准备 Rynx 内置插件");
     try {
         const plugins = await prepareBundledPlugins();
         result.plugins = {
             status: plugins.status,
             changed: [...plugins.installed, ...plugins.updated],
         };
+        progress?.succeed("Rynx 内置插件已就绪");
     }
     catch (error) {
         failed = true;
+        progress?.clear();
+        const detail = errorMessage(error);
         result.plugins = {
             status: "error",
-            detail: errorMessage(error),
+            detail,
         };
+        console.error(`Rynx 内置插件准备失败：${detail}`);
     }
+    progress?.start("正在检查 Rynx Browser");
     const diagnostics = await inspectDaemonDiagnostics();
     if (!diagnostics.browser.supported) {
         result.browser = { action: options.browser, status: "unsupported" };
+        progress?.succeed("当前平台不支持 Rynx Browser");
     }
     else if (diagnostics.browser.installedVersion) {
         result.browser = {
@@ -74,29 +86,42 @@ export async function runSetupCommand(args) {
             status: "ready",
             version: diagnostics.browser.installedVersion,
         };
+        progress?.succeed(`Rynx Browser 已就绪：${diagnostics.browser.installedVersion}`);
     }
     else if (options.browser !== "skip") {
+        progress?.update("正在安装 Rynx Browser");
         try {
             const { createBrowserArtifactManagementService } = await import("@rynx-ai/daemon/browser-artifacts");
-            const installed = await createBrowserArtifactManagementService().install({ channel: "stable" }, options.json
-                ? {}
-                : { onProgress: (message) => console.error(message) });
+            const installed = await createBrowserArtifactManagementService().install({ channel: "stable" }, progress ? { onProgress: (message) => progress.update(message) } : {});
             result.browser = {
                 action: options.browser,
                 status: "ready",
                 version: installed.installed.version,
             };
+            progress?.succeed(`Rynx Browser 已就绪：${installed.installed.version}`);
         }
         catch (error) {
             failed = true;
+            progress?.clear();
+            const detail = errorMessage(error);
             result.browser = {
                 action: options.browser,
                 status: "error",
-                detail: errorMessage(error),
+                detail,
             };
+            console.error(`Rynx Browser 安装失败：${detail}`);
         }
     }
-    if (options.json) {
+    else {
+        progress?.succeed("已跳过 Rynx Browser 安装");
+    }
+    if (interactive && process.env.RYNX_DISTRIBUTION !== "app") {
+        failed = await offerBackgroundServiceSetup() || failed;
+    }
+    if (options.resultFile) {
+        writeJsonAtomically(options.resultFile, result);
+    }
+    else if (options.json) {
         console.log(JSON.stringify(result, null, 2));
     }
     else if (interactive) {
@@ -140,13 +165,25 @@ export async function runDoctorCommand(args) {
         return { id, installed: !probe.error && probe.status === 0 };
     });
     const daemon = await inspectDaemonDiagnostics();
+    const tmuxBin = resolveBundledTmux();
+    const systemDependencies = tmuxBin
+        ? await inspectSystemDependencies({ tmuxBin })
+        : {
+            tmux: {
+                installed: false,
+                detail: BUNDLED_TMUX_UNAVAILABLE_MESSAGE,
+            },
+        };
     const result = {
-        ok: configError === undefined && runtimes.some((runtime) => runtime.installed),
+        ok: configError === undefined &&
+            runtimes.some((runtime) => runtime.installed) &&
+            systemDependencies.tmux.installed,
         configPath: rynxConfigFile(),
         config,
         configError,
         runtimes,
         daemon,
+        systemDependencies,
     };
     if (json)
         console.log(JSON.stringify(result, null, 2));
@@ -159,6 +196,7 @@ export async function runDoctorCommand(args) {
         for (const runtime of runtimes) {
             console.log(`${runtime.id}: ${runtime.installed ? "installed" : "not installed"}`);
         }
+        console.log(`tmux: ${systemDependencies.tmux.installed ? "installed" : "not installed"}`);
         if (daemon.browser.supported) {
             console.log(`browser: ${daemon.browser.installedVersion ?? daemon.browser.error ?? "not installed"}`);
         }
@@ -186,6 +224,17 @@ function parseSetupOptions(args) {
             options.nonInteractive = true;
             continue;
         }
+        if (arg === "--result-file") {
+            if (options.resultFile !== undefined)
+                fail("setup: duplicate option --result-file");
+            const value = args[index + 1];
+            if (!value || value.startsWith("--"))
+                fail("setup: --result-file requires a value");
+            options.resultFile = path.resolve(value);
+            options.nonInteractive = true;
+            index += 1;
+            continue;
+        }
         if (arg === "--install-browser" || arg === "--skip-browser") {
             if (options.browser !== "auto")
                 fail("setup: choose only one Browser action");
@@ -225,6 +274,9 @@ function parseSetupOptions(args) {
             fail(`setup: unknown option ${arg}`);
         }
     }
+    if (options.json && options.resultFile) {
+        fail("setup: choose either --json or --result-file");
+    }
     return options;
 }
 async function collectInteractiveSetup(config) {
@@ -257,19 +309,55 @@ async function collectInteractiveSetup(config) {
     if (prompts.isCancel(host))
         return cancelled();
     config.HOST = host;
-    const logLevel = await prompts.text({
-        message: "Log level",
-        initialValue: String(config.LOG_LEVEL),
-    });
-    if (prompts.isCancel(logLevel))
-        return cancelled();
-    config.LOG_LEVEL = logLevel;
     return true;
 }
 function cancelled() {
     prompts.cancel("Cancelled");
     return false;
 }
+async function offerBackgroundServiceSetup() {
+    const state = inspectAutostart();
+    if (!state.supported) {
+        prompts.log.warn(`Background service setup is unavailable${state.detail ? `: ${state.detail}` : ""}`);
+        return false;
+    }
+    const confirmed = await prompts.confirm({
+        message: state.registered
+            ? "Start the Rynx background service now? (Autostart is already enabled)"
+            : "Start Rynx now and automatically at login?",
+        initialValue: true,
+    });
+    if (prompts.isCancel(confirmed) || !confirmed) {
+        prompts.log.info("Skipped background service setup");
+        return false;
+    }
+    let failed = false;
+    if (!state.registered) {
+        try {
+            const enabled = enableAutostart();
+            prompts.log.success(`Autostart enabled${enabled.registrationPath ? `: ${enabled.registrationPath}` : ""}`);
+            if (enabled.manager === "systemd-user" && enabled.lingerEnabled === false) {
+                prompts.log.warn("Linger is disabled; Rynx stops when this user logs out");
+                if (enabled.lingerEnableCommand) {
+                    prompts.log.info(`Optional, requires sudo and is never run by setup: ${enabled.lingerEnableCommand}`);
+                }
+            }
+        }
+        catch (error) {
+            failed = true;
+            prompts.log.warn(`Could not enable autostart: ${errorMessage(error)}`);
+        }
+    }
+    const startStatus = await runLifecycleCommand("start", [], { quiet: true });
+    if (startStatus === 0) {
+        prompts.log.success("Rynx background service is running");
+    }
+    else {
+        failed = true;
+        prompts.log.warn("Rynx background service failed to start; run `rynx start` for details");
+    }
+    return failed;
+}
 function validateSetupConfig(config) {
     loadConfig({
         HOST: String(config.HOST),
@@ -290,14 +378,16 @@ function readRawConfig() {
     }
 }
 function writeConfigAtomically(config) {
-    const file = rynxConfigFile();
+    writeJsonAtomically(rynxConfigFile(), config);
+}
+function writeJsonAtomically(file, value) {
     const directory = path.dirname(file);
     mkdirSync(directory, { recursive: true, mode: 0o700 });
     const temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.tmp`);
     let descriptor;
     try {
         descriptor = openSync(temporary, "wx", 0o600);
-        writeFileSync(descriptor, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+        writeFileSync(descriptor, `${JSON.stringify(value, null, 2)}\n`, "utf8");
         closeSync(descriptor);
         descriptor = undefined;
         renameSync(temporary, file);

package/dist/commands/skills.js

@@ -1,8 +1,8 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { isSkillPathComponent } from "@rynx-ai/core";
 import { fail } from "./errors.js";
-const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const MAX_SKILL_BYTES = 256 * 1024;
 const BUILTIN_SKILL_NAMES = ["browser", "emulator"];
 export async function runSkillsCommand(args) {
@@ -55,7 +55,7 @@ export async function listBuiltinSkills() {
     return guides.filter((guide) => guide !== null);
 }
 export async function readBuiltinSkill(name, full = false) {
-    if (!SKILL_NAME_PATTERN.test(name))
+    if (!isSkillPathComponent(name))
         return null;
     if (!BUILTIN_SKILL_NAMES.includes(name))
         return null;

package/dist/commands/update.js

@@ -3,7 +3,7 @@ import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync
 import { createRequire } from "node:module";
 import { dirname, join, sep } from "node:path";
 import { rynxHome } from "@rynx-ai/core";
-import { stopStandaloneDaemon } from "../standalone.js";
+import { runLifecycleCommand } from "./lifecycle.js";
 function selfPackage() {
     const require = createRequire(import.meta.url);
     const manifest = require("../../package.json");
@@ -72,7 +72,7 @@ export async function runUpdate(options) {
     if (!releaseLock)
         return 1;
     try {
-        if (await stopStandaloneDaemon() !== 0) {
+        if (await runLifecycleCommand("stop", []) !== 0) {
             console.error("update: could not stop the standalone daemon");
             return 1;
         }

package/dist/control-client.d.ts

@@ -2,8 +2,9 @@ import { type DaemonStatus } from "@rynx-ai/protocol/remote-runtime";
 import { type DaemonCleanupSessionsInput, type DaemonCleanupSessionsResult, type DaemonChromeInspectionConfigureInput, type DaemonChromeInspectionStatus, type DaemonShutdownIfIdleResult } from "@rynx-ai/protocol/control";
 import { type RemoteRuntimeRpcMethod, type RemoteRuntimeRpcParams, type RemoteRuntimeRpcResultFor } from "@rynx-ai/protocol/remote-runtime-rpc";
 import { type PairingOffer } from "@rynx-ai/protocol/direct-runtime";
-import { type RuntimeBrowserBootstrapCredential, type RuntimeBrowserEndpointDescriptor } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+import { type RuntimeBrowserAutomationCommand, type RuntimeBrowserAutomationResult, type RuntimeBrowserBootstrapCredential, type RuntimeBrowserEndpointDescriptor } from "@rynx-ai/protocol/runtime-browser-bootstrap";
 import { type PluginInstallCommitInput, type PluginInstallCommitResult, type PluginInstallPreparation, type PluginInstallPrepareInput, type PluginManagementItem, type PluginManagementState, type PluginMarketplaceAddInput, type PluginMarketplaceItem } from "@rynx-ai/protocol/plugin-management";
+import { type DaemonControlEndpoint } from "./control-endpoint.js";
 export { connectResidentDesktopBrowserHost, type ResidentDesktopBrowserHostConnection, type ResidentDesktopBrowserHostCommandRequest, type ResidentDesktopBrowserHostConnectOptions, type ResidentDesktopBrowserHostFailure, } from "./desktop-browser-host-client.js";
 export interface ResidentDaemonIdentity {
     installationId: string;
@@ -65,7 +66,9 @@ export declare function getResidentDaemonRuntimeStatus(): Promise<DaemonStatus>;
  * when idle. Busy is a normal result so the caller can ask the user to resolve
  * the listed work and explicitly retry.
  */
-export declare function shutdownResidentDaemonIfIdle(): Promise<DaemonShutdownIfIdleResult>;
+export declare function shutdownResidentDaemonIfIdle(endpoint?: DaemonControlEndpoint): Promise<DaemonShutdownIfIdleResult>;
+/** Wait for accepted graceful shutdown before the lifecycle owner is stopped. */
+export declare function waitForResidentDaemonExit(pid: number, timeoutMs?: number): Promise<boolean>;
 export declare function getResidentChromeInspectionStatus(): Promise<DaemonChromeInspectionStatus>;
 export declare function configureResidentChromeInspection(input: DaemonChromeInspectionConfigureInput): Promise<DaemonChromeInspectionStatus>;
 export declare function cleanupResidentSessions(input?: DaemonCleanupSessionsInput): Promise<DaemonCleanupSessionsResult>;
@@ -111,6 +114,24 @@ export declare function readOptionalManagedRuntimeBrowserCredential(env?: NodeJS
 export declare function callManagedRuntimeBrowser<M extends RemoteRuntimeRpcMethod>(credential: RuntimeBrowserBootstrapCredential, method: M, params: RemoteRuntimeRpcParams<M>, options?: {
     signal?: AbortSignal;
 }): Promise<RemoteRuntimeRpcResultFor<M>>;
+/** Execute native page-command argv within the caller's Session on this Runtime. */
+export declare function executeResidentBrowserCommand(command: RuntimeBrowserAutomationCommand, options?: {
+    sessionId?: string;
+    credential?: RuntimeBrowserBootstrapCredential;
+}): Promise<RuntimeBrowserAutomationResult>;
+/** Keep the daemon's bounded public diagnostics, including no-replay guidance. */
+export declare class ResidentBrowserCommandError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: {
+        error: string;
+        code?: string;
+        message?: string;
+        hint?: string;
+        outcome?: "unknown" | "not_started";
+    };
+    constructor(status: number, body: string);
+}
 /** Resolve native CDP for the caller's own Session on this Runtime only. */
 export declare function getResidentRuntimeLocalBrowserEndpoint(options?: {
     env?: NodeJS.ProcessEnv;

package/dist/control-client.js

@@ -4,10 +4,10 @@ import { isDaemonCoreCompatible, parseDaemonStatus, } from "@rynx-ai/protocol/re
 import { DAEMON_CHROME_INSPECTION_PATH, DAEMON_CLEANUP_SESSIONS_PATH, DAEMON_SHUTDOWN_IF_IDLE_PATH, parseDaemonCleanupSessionsResult, parseDaemonChromeInspectionConfigureInput, parseDaemonChromeInspectionStatus, parseDaemonShutdownIfIdleResult, } from "@rynx-ai/protocol/control";
 import { parseRemoteRuntimeRpcRequest, parseRemoteRuntimeRpcResponseForMethod, REMOTE_RUNTIME_RPC_MAX_FRAME_BYTES, REMOTE_RUNTIME_RPC_METHOD_METADATA, } from "@rynx-ai/protocol/remote-runtime-rpc";
 import { parsePairingOffer, } from "@rynx-ai/protocol/direct-runtime";
-import { RUNTIME_BROWSER_BOOTSTRAP_PATH, RUNTIME_BROWSER_CAPABILITY_ENV, RUNTIME_BROWSER_CAPABILITY_HEADER, RUNTIME_BROWSER_CONTEXT_FILE_ENV, RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX, RUNTIME_BROWSER_RPC_PATH, RUNTIME_BROWSER_SESSION_ID_ENV, RUNTIME_BROWSER_SESSION_ID_HEADER, parseRuntimeBrowserBootstrapCredential, parseRuntimeBrowserEndpointDescriptor, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
+import { RUNTIME_BROWSER_BOOTSTRAP_PATH, RUNTIME_BROWSER_CAPABILITY_ENV, RUNTIME_BROWSER_CAPABILITY_HEADER, RUNTIME_BROWSER_CONTEXT_FILE_ENV, RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX, RUNTIME_BROWSER_RPC_PATH, RUNTIME_BROWSER_EXECUTE_PATH, RUNTIME_BROWSER_SESSION_ID_ENV, RUNTIME_BROWSER_SESSION_ID_HEADER, parseRuntimeBrowserBootstrapCredential, parseRuntimeBrowserAutomationCommand, parseRuntimeBrowserEndpointDescriptor, } from "@rynx-ai/protocol/runtime-browser-bootstrap";
 import { parseRuntimeBrowserStateGetParams } from "@rynx-ai/protocol/runtime-browser";
 import { PLUGIN_INSTALL_PREPARATIONS_PATH, PLUGIN_MARKETPLACES_PATH, parsePluginInstallCommitInput, parsePluginInstallCommitResult, parsePluginInstallPreparation, parsePluginInstallPrepareInput, parsePluginManagementItem, parsePluginMarketplaceAddInput, parsePluginMarketplaceItem, pluginInstallCommitPath, pluginInstallPreparationPath, } from "@rynx-ai/protocol/plugin-management";
-import { ensureDaemonControlEndpoint } from "./control-endpoint.js";
+import { ensureDaemonControlEndpoint, } from "./control-endpoint.js";
 export { connectResidentDesktopBrowserHost, } from "./desktop-browser-host-client.js";
 const IDENTITY_TIMEOUT_MS = 5_000;
 const RUNTIME_STATUS_TIMEOUT_MS = 5_000;
@@ -108,15 +108,36 @@ export async function getResidentDaemonRuntimeStatus() {
  * when idle. Busy is a normal result so the caller can ask the user to resolve
  * the listed work and explicitly retry.
  */
-export async function shutdownResidentDaemonIfIdle() {
-    const endpoint = await ensureDaemonControlEndpoint();
-    assertLoopbackOrigin(endpoint.origin);
-    const response = await fetch(`${endpoint.origin}${DAEMON_SHUTDOWN_IF_IDLE_PATH}`, {
-        method: "POST",
-        headers: managementHeaders(endpoint.managementToken),
-        signal: AbortSignal.timeout(DAEMON_SHUTDOWN_TIMEOUT_MS),
-    });
-    const body = await readBoundedResponse(response, DAEMON_SHUTDOWN_RESPONSE_MAX_BYTES);
+export async function shutdownResidentDaemonIfIdle(endpoint) {
+    const resident = endpoint ?? await ensureDaemonControlEndpoint();
+    assertLoopbackOrigin(resident.origin);
+    let response;
+    try {
+        response = await fetch(`${resident.origin}${DAEMON_SHUTDOWN_IF_IDLE_PATH}`, {
+            method: "POST",
+            headers: managementHeaders(resident.managementToken),
+            signal: AbortSignal.timeout(DAEMON_SHUTDOWN_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        // The daemon may close its listener before the 202 reaches the client.
+        // The original PID exiting proves that the requested lifecycle boundary
+        // completed, so the caller can continue with supervisor cleanup.
+        if (await waitForResidentDaemonExit(resident.pid)) {
+            return { outcome: "accepted" };
+        }
+        throw error;
+    }
+    let body;
+    try {
+        body = await readBoundedResponse(response, DAEMON_SHUTDOWN_RESPONSE_MAX_BYTES);
+    }
+    catch (error) {
+        if (response.status === 202 && await waitForResidentDaemonExit(resident.pid)) {
+            return { outcome: "accepted" };
+        }
+        throw error;
+    }
     if (response.status !== 202 && response.status !== 409) {
         throw daemonRequestError("daemon shutdown-if-idle request", response.status, body);
     }
@@ -125,6 +146,9 @@ export async function shutdownResidentDaemonIfIdle() {
         result = parseDaemonShutdownIfIdleResult(JSON.parse(body));
     }
     catch (error) {
+        if (response.status === 202 && await waitForResidentDaemonExit(resident.pid)) {
+            return { outcome: "accepted" };
+        }
         throw new Error(`daemon returned an invalid shutdown-if-idle response: ${messageOf(error)}`);
     }
     if (response.status === 202 && result.outcome !== "accepted" ||
@@ -133,6 +157,25 @@ export async function shutdownResidentDaemonIfIdle() {
     }
     return result;
 }
+/** Wait for accepted graceful shutdown before the lifecycle owner is stopped. */
+export async function waitForResidentDaemonExit(pid, timeoutMs = 120_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        if (!processIsAlive(pid))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return !processIsAlive(pid);
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
 export async function getResidentChromeInspectionStatus() {
     const result = await localManagementJsonRequest(DAEMON_CHROME_INSPECTION_PATH, {
         method: "GET",
@@ -437,6 +480,8 @@ const MANAGED_BROWSER_RPC_METHODS = new Set([
     "browser.page.back",
     "browser.page.forward",
     "browser.page.reload",
+    "browser.request-headers.get",
+    "browser.request-headers.set",
 ]);
 /**
  * Invoke Browser control for the caller's own managed Session. Unlike the
@@ -521,6 +566,59 @@ export async function callManagedRuntimeBrowser(credential, method, params, opti
             : "daemon returned an invalid Runtime call result", response.status, { cause: error, ...(neverRetry ? { outcome: "unknown" } : {}) });
     }
 }
+/** Execute native page-command argv within the caller's Session on this Runtime. */
+export async function executeResidentBrowserCommand(command, options = {}) {
+    const body = parseRuntimeBrowserAutomationCommand(command);
+    const credential = options.credential;
+    const sessionId = credential?.sessionId ?? options.sessionId;
+    if (!sessionId)
+        throw new Error("Browser automation requires a Session");
+    const signal = AbortSignal.timeout(180_000);
+    const endpoint = await ensureDaemonControlEndpoint({ signal });
+    assertLoopbackOrigin(endpoint.origin);
+    const route = credential ? RUNTIME_BROWSER_EXECUTE_PATH : `${RUNTIME_BROWSER_MANAGEMENT_PATH_PREFIX}/${encodeURIComponent(sessionId)}/execute`;
+    const response = await fetch(`${endpoint.origin}${route}`, {
+        method: "POST", signal,
+        headers: {
+            "content-type": "application/json",
+            ...(credential ? { [RUNTIME_BROWSER_SESSION_ID_HEADER]: credential.sessionId, [RUNTIME_BROWSER_CAPABILITY_HEADER]: credential.capability } : managementHeaders(endpoint.managementToken)),
+        },
+        body: JSON.stringify(body),
+    });
+    const raw = await readBoundedResponse(response, 8 * 1024 * 1024);
+    if (!response.ok)
+        throw new ResidentBrowserCommandError(response.status, raw);
+    const result = JSON.parse(raw);
+    if (!result || result.schemaVersion !== 2 || result.sessionId !== sessionId || typeof result.pageId !== "string" ||
+        !Number.isSafeInteger(result.browserGeneration) || result.browserGeneration < 1 || result.completed !== true ||
+        !result.data || typeof result.data !== "object" || Array.isArray(result.data))
+        throw new Error("daemon returned an invalid Browser execution result");
+    return result;
+}
+/** Keep the daemon's bounded public diagnostics, including no-replay guidance. */
+export class ResidentBrowserCommandError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, body) {
+        let parsed;
+        try {
+            parsed = parseJsonObject(body, "invalid Browser error");
+        }
+        catch { /* Plain-text errors remain useful. */ }
+        const bounded = (value, max = 2048) => typeof value === "string" && value.length > 0 ? value.slice(0, max) : undefined;
+        const error = bounded(parsed?.error, 128) ?? "browser_execution_failed";
+        const code = bounded(parsed?.code, 128);
+        const message = bounded(parsed?.message) ?? (parsed === undefined ? bounded(body.trim()) : undefined);
+        const hint = bounded(parsed?.hint);
+        super(`Runtime Browser execution failed (${status}): ${error}${message ? `: ${message}` : ""}${hint ? `\n${hint}` : ""}`);
+        this.status = status;
+        this.name = "ResidentBrowserCommandError";
+        this.code = code ?? error;
+        this.details = { error, ...(code ? { code } : {}), ...(message ? { message } : {}), ...(hint ? { hint } : {}),
+            ...(parsed?.outcome === "unknown" || parsed?.outcome === "not_started" ? { outcome: parsed.outcome } : {}) };
+    }
+}
 /** Resolve native CDP for the caller's own Session on this Runtime only. */
 export async function getResidentRuntimeLocalBrowserEndpoint(options = {}) {
     return (await getResidentRuntimeLocalBrowserAutomationAccess(options)).descriptor;

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

@@ -1,14 +1,36 @@
-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 { DESKTOP_BROWSER_HOST_MAX_BINARY_FRAME_BYTES, DESKTOP_BROWSER_HOST_MAX_CONTROL_FRAME_BYTES, DESKTOP_BROWSER_HOST_MAX_PENDING_COMMANDS, DESKTOP_BROWSER_HOST_MINIMUM_PROTOCOL_VERSION, 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 endpoint = options.endpoint
+        ?? await ensureDaemonControlEndpoint({ signal: options.signal });
+    assertDesktopBrowserHostEndpoint(endpoint);
+    try {
+        return await connectResidentDesktopBrowserHostVersion(options, endpoint, DESKTOP_BROWSER_HOST_PROTOCOL_VERSION);
+    }
+    catch (error) {
+        options.signal?.throwIfAborted();
+        if (!isLegacyProtocolRejection(error))
+            throw error;
+        // V1 daemons reject a V2 hello before issuing a lease. Reconnect once
+        // with their protocol so App and daemon can roll independently. Any
+        // failure after a lease is returned stays on that negotiated connection.
+        return connectResidentDesktopBrowserHostVersion(options, endpoint, DESKTOP_BROWSER_HOST_MINIMUM_PROTOCOL_VERSION).catch((legacyError) => {
+            throw new Error("Desktop Browser Host could not negotiate with the daemon", {
+                cause: new AggregateError([error, legacyError]),
+            });
+        });
+    }
+}
+async function connectResidentDesktopBrowserHostVersion(options, endpoint, protocolVersion) {
     options.signal?.throwIfAborted();
     const hello = parseDesktopBrowserHostClientFrame({
         type: "desktop.browser.host.hello",
-        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+        protocolVersion,
         hostInstanceId: options.hostInstanceId,
         capabilities: {
             semanticPageBinding: options.capabilities.semanticPageBinding,
@@ -19,9 +41,6 @@ export async function connectResidentDesktopBrowserHost(options) {
     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, {
@@ -139,7 +158,7 @@ export async function connectResidentDesktopBrowserHost(options) {
     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")}` : ""}`);
+            terminalError = new DesktopBrowserHostLeaseClosedError(code, `Desktop Browser Host lease closed (${code})${reason.length > 0 ? `: ${reason.toString("utf8")}` : ""}`);
         }
         if (!lease && terminalError)
             leaseReject(terminalError);
@@ -224,7 +243,7 @@ export async function connectResidentDesktopBrowserHost(options) {
                     signal: controller.signal,
                     reply: (result) => settle(command, {
                         type: "desktop.browser.host.reply",
-                        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                        protocolVersion: activeLease.protocolVersion,
                         leaseId: activeLease.leaseId,
                         commandId: command.commandId,
                         ok: true,
@@ -232,7 +251,7 @@ export async function connectResidentDesktopBrowserHost(options) {
                     }),
                     reject: (failure) => settle(command, {
                         type: "desktop.browser.host.reply",
-                        protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                        protocolVersion: activeLease.protocolVersion,
                         leaseId: activeLease.leaseId,
                         commandId: command.commandId,
                         ok: false,
@@ -250,7 +269,7 @@ export async function connectResidentDesktopBrowserHost(options) {
             const nextSequence = eventSequence + 1;
             const frame = parseDesktopBrowserHostClientFrame({
                 type: "desktop.browser.host.event",
-                protocolVersion: DESKTOP_BROWSER_HOST_PROTOCOL_VERSION,
+                protocolVersion: activeLease.protocolVersion,
                 leaseId: activeLease.leaseId,
                 eventSequence: nextSequence,
                 event,
@@ -268,7 +287,7 @@ export async function connectResidentDesktopBrowserHost(options) {
             const encoded = encodeDesktopBrowserHostSurfaceFrame({
                 ...frame,
                 leaseId: activeLease.leaseId,
-            });
+            }, activeLease.protocolVersion);
             await sendBinary(socket, encoded);
         }),
         close: async () => {
@@ -285,6 +304,20 @@ export async function connectResidentDesktopBrowserHost(options) {
         },
     };
 }
+class DesktopBrowserHostLeaseClosedError extends Error {
+    closeCode;
+    constructor(closeCode, message) {
+        super(message);
+        this.closeCode = closeCode;
+        this.name = "DesktopBrowserHostLeaseClosedError";
+    }
+}
+function isLegacyProtocolRejection(error) {
+    return error instanceof DesktopBrowserHostLeaseClosedError &&
+        // 4400 is the pre-V2 daemon's generic invalid-frame response. 1002 covers
+        // standards-based V1 peers; 4406 is the explicit unsupported-version code.
+        (error.closeCode === 1002 || error.closeCode === 4400 || error.closeCode === 4406);
+}
 async function sendBinary(socket, bytes) {
     if (socket.readyState !== WebSocket.OPEN)
         throw new Error("Desktop Browser Host lease is closed");

package/dist/legacy-maintenance.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Remove the retired cross-process replacement fence.
+ *
+ * Older daemons may have left this file behind after an updater crash. The
+ * standalone stop path makes a best-effort attempt once lifecycle ownership is
+ * gone. This compatibility detail is not part of the public lifecycle result.
+ */
+export declare function clearLegacyMaintenanceState(): void;

package/dist/legacy-maintenance.js

@@ -0,0 +1,13 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { rynxHome } from "@rynx-ai/core";
+/**
+ * Remove the retired cross-process replacement fence.
+ *
+ * Older daemons may have left this file behind after an updater crash. The
+ * standalone stop path makes a best-effort attempt once lifecycle ownership is
+ * gone. This compatibility detail is not part of the public lifecycle result.
+ */
+export function clearLegacyMaintenanceState() {
+    rmSync(join(rynxHome(), "maintenance-lease.json"), { force: true });
+}

package/dist/progress-display.d.ts

@@ -0,0 +1,7 @@
+export interface ProgressDisplay {
+    start(message: string): void;
+    update(message: string): void;
+    succeed(message: string): void;
+    clear(): void;
+}
+export declare function createProgressDisplay(): ProgressDisplay;