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

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
@@ -24,48 +24,127 @@ 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
+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
 ```
 
-Inspect before acting:
+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 snapshot --json
+rynx browser exec --page <pageId> -- frame @<iframe-ref>
+rynx browser exec --page <pageId> --json -- snapshot -i
+rynx browser exec --page <pageId> -- frame main
 ```
 
-Use a returned accessibility `ref` for the next action:
+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
+
+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 click --ref <ref> --json
-rynx browser type --ref <ref> --text "hello" --json
+rynx browser headers get --json
 ```
 
-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:
+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 status --json
-rynx browser pages --json
-rynx browser screenshot --output /absolute/path/page.png --json
+rynx browser headers set \
+  --enable \
+  --header 'X-Environment: staging' \
+  --header 'X-Request-Source: rynx' \
+  --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.
+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
   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.

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`,