@rynx-ai/cli 0.1.11-beta.30 → 0.1.11-beta.31

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

@@ -1,5 +1,5 @@
 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" | "close";
+export type BrowserCliSubcommand = "install" | "update" | "version" | "clean" | "open" | "status" | "pages" | "endpoint" | "snapshot" | "navigate" | "click" | "type" | "screenshot" | "headers" | "close";
 export interface BrowserCliArgs {
     subcommand: BrowserCliSubcommand;
     json: boolean;
@@ -17,6 +17,12 @@ export interface BrowserCliArgs {
     quality?: number;
     x?: number;
     y?: number;
+    headersAction?: "get" | "set";
+    headers?: string[];
+    expectedRevision?: string;
+    headersEnabled?: boolean;
+    clearHeaders?: boolean;
+    showHeaderValues?: boolean;
 }
 export interface BrowserCliTarget {
     runtimeSelector: string;

package/dist/browser-cli-args.js

@@ -29,17 +29,23 @@ const SPECS = {
         values: ["--output", "--format", "--quality", "--session"],
         flags: ["--json"],
     },
+    headers: {
+        values: ["--session", "--runtime", "--header", "--expected-revision"],
+        flags: ["--json", "--enable", "--disable", "--clear", "--show-values"],
+        positionalAction: true,
+    },
     close: { values: ["--session", "--runtime"], flags: ["--json"] },
 };
 export function parseBrowserCliArgs(args) {
     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, or close");
+            "snapshot, navigate, click, type, screenshot, headers, or close");
     }
     const spec = SPECS[subcommand];
     const values = new Map();
     const flags = new Set();
+    const headerValues = [];
     const positionals = [];
     for (let index = 1; index < args.length; index += 1) {
         const arg = args[index];
@@ -51,13 +57,17 @@ export function parseBrowserCliArgs(args) {
                 continue;
             }
             if (spec.values.includes(arg)) {
-                if (values.has(arg))
+                if (arg !== "--header" && values.has(arg)) {
                     throw new Error(`browser ${subcommand}: duplicate option ${arg}`);
+                }
                 const value = args[index + 1];
                 if (!value || value.startsWith("--")) {
                     throw new Error(`browser ${subcommand}: ${arg} requires a value`);
                 }
-                values.set(arg, value);
+                if (arg === "--header")
+                    headerValues.push(value);
+                else
+                    values.set(arg, value);
                 index += 1;
                 continue;
             }
@@ -65,13 +75,13 @@ export function parseBrowserCliArgs(args) {
         }
         positionals.push(arg);
     }
-    if (!spec.positionalUrl && positionals.length > 0) {
+    if (!spec.positionalUrl && !spec.positionalAction && positionals.length > 0) {
         throw new Error(`browser ${subcommand}: unexpected argument ${positionals[0]}`);
     }
     if (positionals.length > 1) {
         throw new Error(`browser ${subcommand}: unexpected extra argument ${positionals[1]}`);
     }
-    if (positionals.length === 1 && values.has("--url")) {
+    if (spec.positionalUrl && positionals.length === 1 && values.has("--url")) {
         throw new Error("browser open: pass the URL once, either positionally or with --url");
     }
     const result = {
@@ -82,10 +92,45 @@ export function parseBrowserCliArgs(args) {
         ...(values.has("--version") ? { version: values.get("--version") } : {}),
         ...(values.has("--runtime") ? { runtime: values.get("--runtime") } : {}),
         ...(values.has("--session") ? { session: values.get("--session") } : {}),
-        ...(values.has("--url") || positionals[0]
+        ...(spec.positionalUrl && (values.has("--url") || positionals[0])
             ? { url: values.get("--url") ?? positionals[0] }
             : {}),
     };
+    if (subcommand === "headers") {
+        const action = positionals[0];
+        if (action !== "get" && action !== "set") {
+            throw new Error("browser headers: expected get or set");
+        }
+        if (flags.has("--enable") && flags.has("--disable")) {
+            throw new Error("browser headers set: choose either --enable or --disable");
+        }
+        result.headersAction = action;
+        if (headerValues.length > 0)
+            result.headers = headerValues;
+        if (values.has("--expected-revision")) {
+            result.expectedRevision = nonEmpty(values.get("--expected-revision"), "--expected-revision");
+        }
+        if (flags.has("--enable"))
+            result.headersEnabled = true;
+        if (flags.has("--disable"))
+            result.headersEnabled = false;
+        if (flags.has("--clear"))
+            result.clearHeaders = true;
+        if (flags.has("--show-values"))
+            result.showHeaderValues = true;
+        if (action === "get" && (headerValues.length > 0 ||
+            result.expectedRevision !== undefined ||
+            result.headersEnabled !== undefined ||
+            result.clearHeaders)) {
+            throw new Error("browser headers get: update options are not allowed");
+        }
+        if (action === "set" && result.showHeaderValues) {
+            throw new Error("browser headers set: --show-values is only valid with get");
+        }
+        if (action === "set" && headerValues.length > 0 && result.clearHeaders) {
+            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"))

package/dist/commands/browser.d.ts

@@ -1 +1,5 @@
+import type { RuntimeBrowserRequestHeadersPolicy } from "@rynx-ai/protocol/runtime-browser";
 export declare function runBrowserCommand(args: readonly string[]): Promise<number>;
+export declare function projectRequestHeadersPolicyForOutput(policy: RuntimeBrowserRequestHeadersPolicy, showValues: boolean): RuntimeBrowserRequestHeadersPolicy & {
+    valuesRedacted: boolean;
+};

package/dist/commands/browser.js

@@ -83,6 +83,30 @@ export async function runBrowserCommand(args) {
         return 0;
     }
     const target = await resolveBrowserTarget(parsed);
+    if (parsed.subcommand === "headers") {
+        const current = await callBrowserRuntime(target, "browser.request-headers.get", {
+            sessionId: target.sessionId,
+        });
+        if (parsed.headersAction === "get") {
+            if (parsed.showHeaderValues && target.credential) {
+                fail("browser headers get: --show-values is unavailable inside a managed Session; " +
+                    "use the Session settings UI");
+            }
+            printRequestHeadersPolicy(current, parsed.json, parsed.showHeaderValues === true);
+            return 0;
+        }
+        const headers = parsed.clearHeaders
+            ? []
+            : parsed.headers?.map(parseCliRequestHeader) ?? current.headers;
+        const updated = await callBrowserRuntime(target, "browser.request-headers.set", {
+            sessionId: target.sessionId,
+            expectedRevision: parsed.expectedRevision ?? current.revision,
+            enabled: parsed.headersEnabled ?? current.enabled,
+            headers,
+        });
+        printRequestHeadersPolicy(updated, parsed.json, false);
+        return 0;
+    }
     if (isAutomationCommand(parsed.subcommand)) {
         return runBrowserAutomation(parsed, target);
     }
@@ -252,6 +276,43 @@ function printBrowserPages(state) {
         console.log(`${marker} ${page.pageId}  ${page.url}${title}`);
     }
 }
+function parseCliRequestHeader(value) {
+    const separator = value.indexOf(":");
+    if (separator <= 0) {
+        fail("browser headers set: --header must use 'Name: value'");
+    }
+    const name = value.slice(0, separator).trim();
+    const rawValue = value.slice(separator + 1);
+    return {
+        name,
+        value: rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue,
+    };
+}
+function printRequestHeadersPolicy(policy, json, showValues) {
+    const output = projectRequestHeadersPolicyForOutput(policy, showValues);
+    if (json) {
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    console.log(`Browser request headers ${output.enabled ? "enabled" : "disabled"} · revision ${output.revision}`);
+    if (output.headers.length === 0) {
+        console.log("  (no configured headers)");
+        return;
+    }
+    for (const header of output.headers)
+        console.log(`  ${header.name}: ${header.value}`);
+}
+export function projectRequestHeadersPolicyForOutput(policy, showValues) {
+    return {
+        enabled: policy.enabled,
+        revision: policy.revision,
+        valuesRedacted: !showValues,
+        headers: policy.headers.map((header) => ({
+            name: header.name,
+            value: showValues ? header.value : "[redacted]",
+        })),
+    };
+}
 function isAutomationCommand(subcommand) {
     return subcommand === "snapshot"
         || subcommand === "navigate"

package/dist/control-client.js

@@ -437,6 +437,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

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/package.json

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

package/skill-guides/browser.md

@@ -1,6 +1,6 @@
 ---
 name: browser
-description: Use the bundled Rynx CLI to inspect and automate the Browser owned by the active Rynx Session with snapshots, accessibility refs, navigation, clicks, typing, screenshots, page inspection, and safe failure handling.
+description: Use the bundled Rynx CLI to inspect and automate the Browser owned by the active Rynx Session, and to read or update the Session-wide Browser request-header policy, with safe failure handling.
 ---
 
 # Rynx Browser
@@ -61,6 +61,46 @@ rynx browser screenshot --output /absolute/path/page.png --json
 Do not request or connect to the raw CDP endpoint unless diagnosing Rynx itself.
 Do not close a Browser generation the user still needs.
 
+## Session-wide request headers
+
+Inspect the current policy when needed. Header values are redacted in the
+managed Session CLI so secrets do not enter the Agent transcript:
+
+```sh
+rynx browser headers get --json
+```
+
+Set headers for every current and future Browser page in this Rynx Session.
+The policy covers document and subresource requests to every origin:
+
+```sh
+rynx browser headers set \
+  --enable \
+  --header 'X-Environment: staging' \
+  --header 'X-Request-Source: rynx' \
+  --json
+```
+
+Changes take effect immediately. Existing pages use the new values on their
+next request or refresh; requests already in flight are unchanged. Closing and
+reopening the Session Browser keeps the policy. Deleting the Session or
+restarting the resident daemon removes it, and a forked Session starts with no
+header policy.
+
+`set` reads the current policy internally, so `--disable` without `--header`
+stops sending headers while retaining configured rows without exposing their
+values. Use `--clear` to remove all rows. When an earlier `get` is the basis for
+an edited update, pass its opaque revision with
+`--expected-revision <revision>`; a conflict means another actor changed the
+policy, so fetch it again instead of retrying stale values.
+
+Header names are case-insensitively unique. Browser-controlled or unsafe names
+such as `Authorization`, `Cookie`, `Host`, `Origin`, `Referer`, `User-Agent`,
+`Content-Length`, `Proxy-*`, and `Sec-*` are rejected. Do not put header values
+in logs, chat messages, or error reports. Both text and JSON CLI output use
+`[redacted]`; use the Session settings UI when a human must inspect or edit a
+sensitive value. Do not attempt to bypass this boundary from an active Session.
+
 ## Failure handling
 
 - On endpoint access failure, follow **Sandbox boundary** and make no fallback

package/skills/rynx-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rynx-cli
-description: Use the bundled `rynx` CLI when a task needs to inspect or automate the Browser or Emulator owned by the active Rynx Session. Load the version-matched Browser or Emulator guide from the CLI before operating it. Prefer this over direct CDP, browser drivers, `serve-sim`, `simctl`, adb, guessed ports, or guessed App installations.
+description: Use the bundled `rynx` CLI when a task needs to inspect or automate the Browser or Emulator owned by the active Rynx Session, or configure Session-wide Browser request headers. Load the version-matched Browser or Emulator guide from the CLI before operating it. Prefer this over direct CDP, browser drivers, Header-modifying extensions, `serve-sim`, `simctl`, adb, guessed ports, or guessed App installations.
 ---
 
 # Rynx CLI
@@ -21,9 +21,14 @@ rynx skills get browser
 rynx skills get emulator
 ```
 
-Use `browser` for Browser inspection/automation and `emulator` for mobile device
-inspection/control. Do not load an unrelated guide. These commands read guides
-shipped in the exact CLI npm package and do not contact the daemon or network.
+Use `browser` for Browser inspection/automation and Session-wide Browser request
+headers, and `emulator` for mobile device inspection/control. Do not load an
+unrelated guide. These commands read guides shipped in the exact CLI npm
+package and do not contact the daemon or network.
+
+The managed Session CLI redacts configured Browser Header values. Do not try to
+recover them through alternate endpoints or tools; a human can inspect or edit
+sensitive values in Session settings.
 
 If `rynx skills get <topic>` itself cannot execute, report its exact error and
 stop. Do not scan `/Applications`, use `find` or `mdfind`, run `open`, `open -a`,