@rynx-ai/cli 0.1.11-beta.45 → 0.1.11-beta.48

package/dist/browser-cli-args.d.ts

@@ -1,22 +1,16 @@
 import type { RuntimeBrowserBootstrapCredential } from "@rynx-ai/protocol/runtime-browser-bootstrap";
-export type BrowserCliSubcommand = "install" | "update" | "version" | "clean" | "open" | "status" | "pages" | "endpoint" | "snapshot" | "navigate" | "click" | "type" | "screenshot" | "headers" | "close";
+export type BrowserCliSubcommand = "exec" | "install" | "update" | "version" | "clean" | "open" | "status" | "pages" | "endpoint" | "headers" | "close";
 export interface BrowserCliArgs {
     subcommand: BrowserCliSubcommand;
     json: boolean;
     ensure: boolean;
+    argv?: string[];
     channel?: string;
     version?: string;
     runtime?: string;
     session?: string;
+    page?: string;
     url?: string;
-    ref?: string;
-    selector?: string;
-    text?: string;
-    output?: string;
-    format?: "png" | "jpeg" | "webp";
-    quality?: number;
-    x?: number;
-    y?: number;
     headersAction?: "get" | "set";
     headers?: string[];
     expectedRevision?: string;

package/dist/browser-cli-args.js

@@ -1,4 +1,5 @@
 const SPECS = {
+    exec: { values: ["--session", "--page"], flags: ["--json"] },
     install: { values: ["--channel", "--version"], flags: ["--json"] },
     update: { values: ["--channel"], flags: ["--json"] },
     version: { values: [], flags: ["--json"] },
@@ -11,24 +12,6 @@ const SPECS = {
     status: { values: ["--session", "--runtime"], flags: ["--json"] },
     pages: { values: ["--session", "--runtime"], flags: ["--json"] },
     endpoint: { values: ["--session"], flags: ["--ensure", "--json"] },
-    snapshot: { values: ["--session"], flags: ["--json"] },
-    navigate: {
-        values: ["--url", "--session"],
-        flags: ["--json"],
-        positionalUrl: true,
-    },
-    click: {
-        values: ["--ref", "--selector", "--x", "--y", "--session"],
-        flags: ["--json"],
-    },
-    type: {
-        values: ["--ref", "--selector", "--text", "--session"],
-        flags: ["--json"],
-    },
-    screenshot: {
-        values: ["--output", "--format", "--quality", "--session"],
-        flags: ["--json"],
-    },
     headers: {
         values: ["--session", "--runtime", "--header", "--expected-revision"],
         flags: ["--json", "--enable", "--disable", "--clear", "--show-values"],
@@ -37,10 +20,18 @@ const SPECS = {
     close: { values: ["--session", "--runtime"], flags: ["--json"] },
 };
 export function parseBrowserCliArgs(args) {
+    let argv;
+    if (args[0] === "exec") {
+        const boundary = args.indexOf("--");
+        if (boundary < 1 || boundary === args.length - 1)
+            throw new Error("browser exec: use rynx browser exec [--page <id>] -- <agent-browser command and arguments>");
+        argv = args.slice(boundary + 1);
+        args = args.slice(0, boundary);
+    }
     const subcommand = args[0];
     if (!isBrowserSubcommand(subcommand)) {
         throw new Error("browser: expected install, update, version, clean, open, status, pages, endpoint, " +
-            "snapshot, navigate, click, type, screenshot, headers, or close");
+            "exec, headers, or close; page actions use browser exec -- <agent-browser command>");
     }
     const spec = SPECS[subcommand];
     const values = new Map();
@@ -88,10 +79,12 @@ export function parseBrowserCliArgs(args) {
         subcommand,
         json: flags.has("--json"),
         ensure: flags.has("--ensure"),
+        ...(argv ? { argv } : {}),
         ...(values.has("--channel") ? { channel: values.get("--channel") } : {}),
         ...(values.has("--version") ? { version: values.get("--version") } : {}),
         ...(values.has("--runtime") ? { runtime: values.get("--runtime") } : {}),
         ...(values.has("--session") ? { session: values.get("--session") } : {}),
+        ...(values.has("--page") ? { page: nonEmpty(values.get("--page"), "--page") } : {}),
         ...(spec.positionalUrl && (values.has("--url") || positionals[0])
             ? { url: values.get("--url") ?? positionals[0] }
             : {}),
@@ -131,49 +124,6 @@ export function parseBrowserCliArgs(args) {
             throw new Error("browser headers set: --clear cannot be combined with --header");
         }
     }
-    if (values.has("--ref"))
-        result.ref = nonEmpty(values.get("--ref"), "--ref");
-    if (values.has("--selector"))
-        result.selector = nonEmpty(values.get("--selector"), "--selector");
-    if (values.has("--text"))
-        result.text = values.get("--text");
-    if (values.has("--output"))
-        result.output = nonEmpty(values.get("--output"), "--output");
-    if (values.has("--format")) {
-        const format = values.get("--format");
-        if (format !== "png" && format !== "jpeg" && format !== "webp") {
-            throw new Error(`browser screenshot: --format must be png, jpeg, or webp`);
-        }
-        result.format = format;
-    }
-    if (values.has("--quality")) {
-        result.quality = integer(values.get("--quality"), "--quality", 0, 100);
-    }
-    if (values.has("--x"))
-        result.x = finiteNumber(values.get("--x"), "--x");
-    if (values.has("--y"))
-        result.y = finiteNumber(values.get("--y"), "--y");
-    if (subcommand === "navigate" && !result.url) {
-        throw new Error("browser navigate: URL is required");
-    }
-    if (subcommand === "click") {
-        const targets = Number(result.ref !== undefined)
-            + Number(result.selector !== undefined)
-            + Number(result.x !== undefined || result.y !== undefined);
-        if (targets !== 1 || (result.x === undefined) !== (result.y === undefined)) {
-            throw new Error("browser click: pass exactly one of --ref, --selector, or both --x and --y");
-        }
-    }
-    if (subcommand === "type") {
-        if ((result.ref === undefined) === (result.selector === undefined)) {
-            throw new Error("browser type: pass exactly one of --ref or --selector");
-        }
-        if (result.text === undefined)
-            throw new Error("browser type: --text is required");
-    }
-    if (subcommand === "screenshot" && !result.output) {
-        throw new Error("browser screenshot: --output is required");
-    }
     return result;
 }
 /** Resolve authority without ever turning a managed Session into an operator. */
@@ -211,16 +161,3 @@ function nonEmpty(value, option) {
         throw new Error(`${option} must not be empty`);
     return value;
 }
-function finiteNumber(value, option) {
-    const parsed = Number(value);
-    if (!Number.isFinite(parsed))
-        throw new Error(`${option} must be a finite number`);
-    return parsed;
-}
-function integer(value, option, minimum, maximum) {
-    const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
-        throw new Error(`${option} must be an integer from ${minimum} to ${maximum}`);
-    }
-    return parsed;
-}

package/dist/commands/browser.js

@@ -1,9 +1,5 @@
-import { writeFile } from "node:fs/promises";
-import path from "node:path";
-import { connectBrowserAutomation, } from "@rynx-ai/browser-cdp";
-import WebSocket from "ws";
 import { parseBrowserCliArgs, resolveBrowserCliTarget, } from "../browser-cli-args.js";
-import { callManagedRuntimeBrowser, callResidentRuntime, getResidentRuntimeLocalBrowserAutomationAccess, getResidentRuntimeLocalBrowserEndpoint, readOptionalManagedRuntimeBrowserCredential, } from "../control-client.js";
+import { callManagedRuntimeBrowser, callResidentRuntime, executeResidentBrowserCommand, ResidentBrowserCommandError, getResidentRuntimeLocalBrowserEndpoint, readOptionalManagedRuntimeBrowserCredential, } from "../control-client.js";
 import { createProgressDisplay } from "../progress-display.js";
 import { fail } from "./errors.js";
 export async function runBrowserCommand(args) {
@@ -107,8 +103,23 @@ export async function runBrowserCommand(args) {
         printRequestHeadersPolicy(updated, parsed.json, false);
         return 0;
     }
-    if (isAutomationCommand(parsed.subcommand)) {
-        return runBrowserAutomation(parsed, target);
+    if (parsed.subcommand === "exec") {
+        try {
+            const result = await executeResidentBrowserCommand({ argv: parsed.argv, ...(parsed.page ? { pageId: parsed.page } : {}) }, { sessionId: target.sessionId, credential: target.credential });
+            if (!parsed.json && typeof result.data?.help === "string")
+                console.log(result.data.help);
+            else if (!parsed.json && typeof result.data.snapshot === "string")
+                console.log(result.data.snapshot);
+            else
+                console.log(JSON.stringify(result, null, 2));
+            return 0;
+        }
+        catch (error) {
+            if (!(error instanceof ResidentBrowserCommandError))
+                throw error;
+            console.error(parsed.json ? JSON.stringify({ ...error.details, status: error.status }) : error.message);
+            return 1;
+        }
     }
     const sessionId = target.sessionId;
     if (parsed.subcommand === "open") {
@@ -157,86 +168,6 @@ function browserReleaseChannel(value) {
     }
     return normalized;
 }
-async function runBrowserAutomation(parsed, target) {
-    if (target.runtimeSelector !== "local") {
-        fail(`browser ${parsed.subcommand}: automation is available only on the local Runtime`);
-    }
-    const automationAccess = await getResidentRuntimeLocalBrowserAutomationAccess({
-        ...(target.credential ? {} : { sessionId: target.sessionId }),
-    });
-    const descriptor = automationAccess.descriptor;
-    let client;
-    try {
-        client = await connectBrowserAutomation({
-            endpoint: descriptor.endpoint,
-            ...(descriptor.pageTargetId ? { pageTargetId: descriptor.pageTargetId } : {}),
-            referenceKey: automationAccess.referenceKey,
-            createWebSocket: (endpoint) => new WebSocket(endpoint),
-        });
-        if (parsed.subcommand === "snapshot") {
-            const snapshot = await client.snapshot();
-            if (parsed.json) {
-                console.log(JSON.stringify({
-                    sessionId: descriptor.sessionId,
-                    browserGeneration: descriptor.browserGeneration,
-                    snapshot,
-                }, null, 2));
-            }
-            else {
-                printAutomationSnapshot(snapshot.nodes);
-            }
-            return 0;
-        }
-        if (parsed.subcommand === "navigate") {
-            const navigation = await client.navigate(parsed.url);
-            printAutomationResult(parsed, descriptor.browserGeneration, navigation);
-            return 0;
-        }
-        if (parsed.subcommand === "click") {
-            const clickTarget = parsed.ref !== undefined
-                ? { ref: parsed.ref }
-                : parsed.selector !== undefined
-                    ? { selector: parsed.selector }
-                    : { x: parsed.x, y: parsed.y };
-            await client.click(clickTarget);
-            printAutomationResult(parsed, descriptor.browserGeneration);
-            return 0;
-        }
-        if (parsed.subcommand === "type") {
-            const typeTarget = parsed.ref !== undefined
-                ? { ref: parsed.ref }
-                : { selector: parsed.selector };
-            await client.type(typeTarget, parsed.text);
-            printAutomationResult(parsed, descriptor.browserGeneration);
-            return 0;
-        }
-        const screenshot = await client.screenshot({
-            ...(parsed.format ? { format: parsed.format } : {}),
-            ...(parsed.quality !== undefined ? { quality: parsed.quality } : {}),
-        });
-        const output = path.resolve(parsed.output);
-        if (!path.isAbsolute(parsed.output)) {
-            fail("browser screenshot: --output must be an absolute path");
-        }
-        await writeFile(output, Buffer.from(screenshot.data, "base64"), { mode: 0o600 });
-        if (parsed.json) {
-            console.log(JSON.stringify({
-                completed: true,
-                browserGeneration: descriptor.browserGeneration,
-                output,
-                format: screenshot.format,
-                mimeType: screenshot.mimeType,
-            }, null, 2));
-        }
-        else {
-            console.log(output);
-        }
-        return 0;
-    }
-    finally {
-        client?.close();
-    }
-}
 async function resolveBrowserTarget(args) {
     const credential = await readOptionalManagedRuntimeBrowserCredential();
     try {
@@ -313,34 +244,3 @@ export function projectRequestHeadersPolicyForOutput(policy, showValues) {
         })),
     };
 }
-function isAutomationCommand(subcommand) {
-    return subcommand === "snapshot"
-        || subcommand === "navigate"
-        || subcommand === "click"
-        || subcommand === "type"
-        || subcommand === "screenshot";
-}
-function printAutomationResult(parsed, browserGeneration, result = {}) {
-    if (parsed.json) {
-        console.log(JSON.stringify({
-            completed: true,
-            browserGeneration,
-            ...result,
-        }, null, 2));
-    }
-    else {
-        console.log(`Browser ${parsed.subcommand} completed.`);
-    }
-}
-function printAutomationSnapshot(nodes) {
-    if (nodes.length === 0) {
-        console.log("(empty accessibility tree)");
-        return;
-    }
-    for (const node of nodes) {
-        const name = node.name ? ` ${JSON.stringify(node.name)}` : "";
-        const value = node.value ? ` value=${JSON.stringify(node.value)}` : "";
-        const ref = node.ref ? ` ref=${node.ref}` : "";
-        console.log(`${node.role}${name}${value}${ref}`);
-    }
-}

package/dist/control-client.d.ts

@@ -2,7 +2,7 @@ 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";
@@ -114,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,7 +4,7 @@ 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";
@@ -566,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/usage.d.ts

@@ -1 +1 @@
-export declare const USAGE = "Usage: rynx <command>\n\nGeneral:\n  version [--json] | --version\n                     print the installed Rynx version\n\nSetup:\n  setup [--non-interactive] [--default-runtime <codex|traex|claude>]\n        [--host <host>] [--port <port>] [--log-level <level>]\n        [--install-browser|--skip-browser] [--json|--result-file <path>]\n                     initialize configuration and local dependencies\n  doctor             read-only health check\n\nLifecycle:\n  start | restart | stop [--if-idle] | status [--json] | logs\n  autostart enable|disable|status\n  update [version] [--check] [--json]\n\nPlugins:\n  market list\n  market add <git-or-local-source> [--alias <id>]\n  market refresh [market-id]\n  market remove <market-id>\n  plugin list\n  plugin install <source|plugin@market> [--force] [--expect-digest <sha256-...>]\n  plugin update <plugin@market> [--expect-digest <sha256-...>]\n  plugin enable|disable|uninstall <plugin@market>\n  plugin <plugin@market> <command>  invoke a plugin-owned command\n\nAgents:\n  agent list\n  agent show <id>\n  agent add <id>\n  agent rm <id>\n\nBuiltin Skills:\n  skills list [--json]\n  skills get <browser|emulator> [--full] [--json]\n\nMaintenance:\n  cleanup sessions [--dry-run]\n\nEmulator:\n  emulator <args...>\n\nRemote Runtime:\n  runtime share --address <host|ws-url> [--label <label>] [--json]\n  runtime add --pairing-code <rynx://...> [--name <name>]\n  runtime list [--json]\n  runtime test <local|daemon-id> [--json]\n  runtime forget <daemon-id>\n  runtime clients list [--json]\n  runtime clients revoke <grant-id>\n\nSessions:\n  session fork <session-id> [--title <title>] [--json]\n\nBrowser:\n  browser install|update|version|clean [...]\n  browser open [url] [--session <id>] [--runtime <local|daemon-id>] [--json]\n  browser status|pages|close [--session <id>] [--runtime <local|daemon-id>] [--json]\n  browser endpoint [--ensure] [--session <local-id>] [--json]\n  browser snapshot [--session <local-id>] [--json]\n  browser navigate <url> [--session <local-id>] [--json]\n  browser click (--ref <ref>|--selector <css>|--x <n> --y <n>) [--session <local-id>] [--json]\n  browser type (--ref <ref>|--selector <css>) --text <text> [--session <local-id>] [--json]\n  browser screenshot --output <absolute-path> [--session <local-id>] [--json]\n";
+export declare const USAGE = "Usage: rynx <command>\n\nGeneral:\n  version [--json] | --version\n                     print the installed Rynx version\n\nSetup:\n  setup [--non-interactive] [--default-runtime <codex|traex|claude>]\n        [--host <host>] [--port <port>] [--log-level <level>]\n        [--install-browser|--skip-browser] [--json|--result-file <path>]\n                     initialize configuration and local dependencies\n  doctor             read-only health check\n\nLifecycle:\n  start | restart | stop [--if-idle] | status [--json] | logs\n  autostart enable|disable|status\n  update [version] [--check] [--json]\n\nPlugins:\n  market list\n  market add <git-or-local-source> [--alias <id>]\n  market refresh [market-id]\n  market remove <market-id>\n  plugin list\n  plugin install <source|plugin@market> [--force] [--expect-digest <sha256-...>]\n  plugin update <plugin@market> [--expect-digest <sha256-...>]\n  plugin enable|disable|uninstall <plugin@market>\n  plugin <plugin@market> <command>  invoke a plugin-owned command\n\nAgents:\n  agent list\n  agent show <id>\n  agent add <id>\n  agent rm <id>\n\nBuiltin Skills:\n  skills list [--json]\n  skills get <browser|emulator> [--full] [--json]\n\nMaintenance:\n  cleanup sessions [--dry-run]\n\nEmulator:\n  emulator <args...>\n\nRemote Runtime:\n  runtime share --address <host|ws-url> [--label <label>] [--json]\n  runtime add --pairing-code <rynx://...> [--name <name>]\n  runtime list [--json]\n  runtime test <local|daemon-id> [--json]\n  runtime forget <daemon-id>\n  runtime clients list [--json]\n  runtime clients revoke <grant-id>\n\nSessions:\n  session fork <session-id> [--title <title>] [--json]\n\nBrowser:\n  browser install|update|version|clean [...]\n  browser open [url] [--session <id>] [--runtime <local|daemon-id>] [--json]\n  browser status|pages|close [--session <id>] [--runtime <local|daemon-id>] [--json]\n  browser endpoint [--ensure] [--session <local-id>] [--json]\n  browser exec [--page <id>] [--session <local-id>] [--json] -- <agent-browser command and args>\n";

package/dist/usage.js

@@ -60,9 +60,5 @@ Browser:
   browser open [url] [--session <id>] [--runtime <local|daemon-id>] [--json]
   browser status|pages|close [--session <id>] [--runtime <local|daemon-id>] [--json]
   browser endpoint [--ensure] [--session <local-id>] [--json]
-  browser snapshot [--session <local-id>] [--json]
-  browser navigate <url> [--session <local-id>] [--json]
-  browser click (--ref <ref>|--selector <css>|--x <n> --y <n>) [--session <local-id>] [--json]
-  browser type (--ref <ref>|--selector <css>) --text <text> [--session <local-id>] [--json]
-  browser screenshot --output <absolute-path> [--session <local-id>] [--json]
+  browser exec [--page <id>] [--session <local-id>] [--json] -- <agent-browser command and args>
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/cli",
-  "version": "0.1.11-beta.45",
+  "version": "0.1.11-beta.48",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rynx-ai/rynx.git",
@@ -51,12 +51,11 @@
   "dependencies": {
     "@clack/prompts": "^1.6.0",
     "ws": "^8.21.0",
-    "@rynx-ai/core": "0.1.11-beta.45",
-    "@rynx-ai/daemon": "0.1.11-beta.45",
-    "@rynx-ai/browser-cdp": "0.1.11-beta.45",
-    "@rynx-ai/emulator": "0.1.11-beta.45",
-    "@rynx-ai/protocol": "0.1.11-beta.45",
-    "@rynx-ai/tmux": "0.1.11-beta.45"
+    "@rynx-ai/core": "0.1.11-beta.48",
+    "@rynx-ai/daemon": "0.1.11-beta.48",
+    "@rynx-ai/emulator": "0.1.11-beta.48",
+    "@rynx-ai/protocol": "0.1.11-beta.48",
+    "@rynx-ai/tmux": "0.1.11-beta.48"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"

package/skill-guides/browser.md

@@ -24,42 +24,79 @@ installation, App, browser, or service. Do not scan `/Applications`, use `find`
 or `mdfind`, run `open`, `open -a`, or `osascript`, inspect Preview/dev builds,
 or launch/relaunch a Rynx App or daemon.
 
-## Core loop
+## Core loop: upstream argv, not Rynx action aliases
 
-Open or navigate the Session Browser when needed:
+Rynx owns Session/Browser/Page resources. All page operations use one general
+entry point; the retired snapshot/click/type/navigate/screenshot aliases are
+not accepted.
 
 ```sh
 rynx browser open https://example.com --json
-rynx browser navigate https://example.com/next --json
-```
-
-Inspect before acting:
-
-```sh
-rynx browser snapshot --json
-```
-
-Use a returned accessibility `ref` for the next action:
-
-```sh
-rynx browser click --ref <ref> --json
-rynx browser type --ref <ref> --text "hello" --json
+rynx browser pages --json
+rynx browser exec -- --help
+rynx browser exec --page <pageId> --json -- snapshot -i
+rynx browser exec --page <pageId> --json -- click @<ref>
+rynx browser exec --page <pageId> --json -- fill @<ref> "带空格的中文"
+rynx browser exec --page <pageId> --json -- screenshot /absolute/path/page.png
 ```
 
-Take a fresh snapshot after navigation or substantial DOM replacement because
-old refs become stale. Use `--selector` only when no useful accessibility ref
-exists. Use coordinate clicks only as a final fallback after a screenshot.
-
-Inspect pages and save visual evidence with:
+Everything after the separator is an argv array sent to the selected native
+agent-browser CLI, without a shell or a second string parser. New upstream
+page commands/options do not require a Rynx command mapping. Command-first
+syntax is required. Use upstream help from this exact engine for frame, wait,
+find, get, scroll, keyboard and other operations; do not copy a command table
+from a different installed version. The outer --json controls Rynx output;
+do not pass an inner --json or override --session, --cdp, configuration,
+provider, namespace, Browser lifecycle or helper settings.
+
+JSON is schemaVersion 2 with sessionId, browserGeneration, pageId, driverVersion
+and upstream data. A snapshot has data.snapshot (text) and data.refs (map).
+Upstream data and native refs are returned unchanged. Use the native refs from
+the latest response (for example @e1); do not invent them. Rynx does not wrap,
+translate or track refs. Ref validity belongs to agent-browser, not Rynx.
+For multi-page tasks, keep --page fixed for the snapshot and subsequent actions:
+refs do not identify their originating Page. Without --page, the command targets
+the Session's current Page when admitted. A missing explicit Page never falls
+back to a neighbor, and switching tabs cannot redirect an already queued command.
+
+Frame selection is also upstream state for this Page helper:
 
 ```sh
-rynx browser status --json
-rynx browser pages --json
-rynx browser screenshot --output /absolute/path/page.png --json
+rynx browser exec --page <pageId> -- frame @<iframe-ref>
+rynx browser exec --page <pageId> --json -- snapshot -i
+rynx browser exec --page <pageId> -- frame main
 ```
 
-Do not request or connect to the raw CDP endpoint unless diagnosing Rynx itself.
-Do not close a Browser generation the user still needs.
+Use the latest native references after snapshot, annotated screenshot or diff;
+these commands may replace the engine's reference map. Take a fresh snapshot
+after switching frames, navigation, substantial DOM replacement or helper/engine
+restart. Old native ref numbers may be reused; Rynx adds no stale-ref protection.
+type inserts; fill replaces, exactly as documented by the selected engine.
+Screenshot formats/options also follow that engine; Rynx does not implement
+a parallel image encoder. Use absolute output paths; default helper artifacts
+are temporary and may disappear on helper cleanup.
+
+Commands serialize per Page. Different Pages progress independently. An active
+human Control lease rejects Agent writes until released. An outcome_unknown
+error means a write may already have happened: inspect, never blindly replay.
+A complete upstream command error is returned without destroying the helper.
+
+Do not request raw CDP, change the engine, start/replace a Browser outside Rynx,
+or close a Browser generation the user still needs. Resource creation/close,
+request-header policy and the human 9333 inspection gateway stay Rynx-owned.
+
+## Engine upgrades (operators only)
+
+The default engine is bundled and pinned. An operator may set the absolute
+native executable path in the Runtime's config.json using
+RYNX_AGENT_BROWSER_EXECUTABLE. This is a daemon-owner setting, not an Agent
+argument and not a PATH fallback. Select a versioned agent-browser native
+binary for the Runtime OS/architecture, then restart the Runtime after changing
+the setting. Upgrading compatible engine versions requires no Rynx CLI build
+or new page-command mappings. Re-run real backend conformance before promoting
+an engine; an upstream CDP/lifecycle/transport breaking change can still require
+an adapter update. Ref names and command-result fields need no Rynx mapping.
+Never upgrade silently in the middle of an Agent action.
 
 ## Session-wide request headers
 
@@ -105,7 +142,9 @@ sensitive value. Do not attempt to bypass this boundary from an active Session.
 
 - On endpoint access failure, follow **Sandbox boundary** and make no fallback
   attempt.
-- On `stale reference`, take a new snapshot and retry once.
+- On an upstream ref error or `driver_restarted`, take a new snapshot on the same
+  --page and re-evaluate the intended action. Do not replay an action whose
+  outcome was reported as unknown.
 - On `busy`, preserve the current Turn or Terminal for the user to resolve.
 - On an unavailable capability, report the missing App integration or macOS
   permission; do not install an unpinned replacement.