Evoui Browser

Evoui Browser

The host Agent owns the business objective, page interpretation, and next action. Evoui records Managed calls, gates Replay of verified mechanical steps, and conservatively publishes reusable knowledge from finished Runs. Use the agent-browser documentation only as internal operating references; it does not trigger this Skill on its own.

In this contract, stock means upstream agent-browser commands, arguments, and results such as open, snapshot -i, and click @e3. Evoui passes stock calls through without changing their semantics.

Use exactly one execution path:

Managed → Domain Knowledge → Browser Session → Observe/Decide/Act/Verify → Finish → Evolution Decision → Terminal Cleanup → Report
Transparent → Stock Result → Report

EVOUI="/absolute/path/to/this-skill/scripts/evoui.py"
EVOUI_ROOT="${EVOUI_HOME:-$HOME/.evoui}"
EVOUI_PROFILE="default"                  # Replace only when the user specifies a Profile
EVOUI_SESSION="evoui-${EVOUI_PROFILE}"   # Replace only when the user specifies a Session

Leave EVOUI_DEBUG_PLAN_TRACE unset in normal mode. When the user explicitly asks to debug Evoui, choose and export one non-empty trace path for the entire Managed Run. Every Plan call and the terminal cleanup must inherit the same environment; never enable, disable, or change the path mid-Run.

Managed argv, stdin, and JSON results are written to local evidence. Evoui is not a redaction, credential-protection, or privacy-isolation boundary.

1. Select the execution path and load its contracts

1. Use Managed by default: operate agent-browser normally, record every call in a Run, and optionally attach Replay as needed. Use Transparent for interactive REPL, MCP/stdio, long-running streams and other calls that do not terminate on their own, or a complete stock command that the user explicitly asks to execute unchanged. A browser objective that requires the Agent to design the browser actions remains Managed. Keep the same path for the entire task; mixing unrecorded Transparent calls into a Managed task leaves Evolution with incomplete evidence.

2. Before reading, saving, or transmitting page or browser output—including page text, HAR files, screenshots, and video—or acting on that output, read the browser trust boundaries in full.

3. For Managed, read the stock agent-browser operating contract, Browser Runtime, and Evoui Plan in full, then continue to section 2. Before starting a Run, a control-plane stock read such as session list may run without creating one; it does not change the execution path.

4. For Transparent, execute the complete stock argv or interactive/long-running invocation directly without loading the day-to-day operating contracts. If the user provides a browser objective and the Agent must design stock calls, use Managed instead. When the stock result needs interpretation, read the stock agent-browser operating contract in full before executing:

   python3 "$EVOUI" <stock argv>

   The wrapper preserves argv, stdin/stdout/stderr, TTY behavior, signals, and exit code exactly. Transparent creates no Run or knowledge and has no Finish, Evolution, or terminal cleanup. After the stock call exits, report its result and stop this workflow. Only the environment-recovery branch described in item 6 may make limited retry attempts, and it must keep the same execution path.

5. Load the following references only to design the corresponding Managed call or when the user asks for interpretation of its corresponding Transparent result. Executing a complete stock argv unchanged does not by itself load a reference merely because the argv contains one of its flags or subcommands:

   • For uncommon commands whose syntax is not covered by the already loaded Evoui references, or for network/HAR, accessibility, React, Web Vitals, or device-emulation work, read the complete command reference.
   • When the day-to-day contract does not fully explain ref generation, scoped snapshots, or iframe refs, read the snapshot and ref reference.
   • When the user explicitly requests cookies, state, the auth vault, or programmatic authentication, read authentication options.
   • When the user explicitly chooses a custom Session, restore, or multiple isolated instances, read Session capabilities.
   • When the task requires a Chrome performance trace, read profiling.
   • When the user requests a proxy, regional egress, or an enterprise network, read proxy support.
   • When the user requests a demonstration or debugging video, read video recording.
   • When the target uses WebGPU or screenshots or video show a black canvas, read WebGPU support.

6. Do not probe dependencies, versions, installation, or doctor on the normal path. Read Browser Environment Recovery only after a missing command, browser_unavailable, a daemon or Chrome startup failure, or an incompatibility between the actual CLI and an already loaded reference. Recover within the current execution path.

2. Load knowledge for the current domain

Derive the lowercase hostname from the target URL, then use Knowledge Discovery to inspect the domain manifest. Only when it finds a usable SiteMap or a Procedure candidate relevant to the task, read Knowledge Consumption and the selected exact revision. Treat SiteMap entries only as navigation guidance and Procedures only as candidate mechanical actions; fresh page state always wins. Missing or unusable knowledge disables Replay, while the task continues normally with stock calls.

3. Prepare the browser session

1. When the user does not specify a Profile, use the logical Profile default and omit --profile when creating a Run. Otherwise, use the specified logical name. When the user does not specify a Session, use the Profile's stable default Session, evoui-<profile>. Validate an explicitly requested Session or namespace with the Evoui Plan safe-name rules before using it.

2. Use Browser Runtime to inspect the selected Session with a read-only control-plane call. If it exists, reuse it across Runs and perform a fresh read; otherwise, start it once. Leave every other Session untouched. Keep one Profile and binding throughout a normal Run.

3. Keep the default Session headed, and give every Managed Browser Plan for that headed Session the same environment:

   AGENT_BROWSER_HEADED=1 python3 "$EVOUI" --evoui plan ...

   When the user explicitly requests headless mode, choose the Session and mode under Browser Runtime instead.

4. For a fresh Session, make the first Browser Plan a stock-only open <target URL> and obtain a fresh URL, title, and interactive snapshot. For a reused Session, first inspect its tabs and fresh page state. Only when no usable task page exists, perform the same stock-only open in the selected primary tab, following the Browser Runtime recipe.

5. When login, a CAPTCHA, permissions, or human confirmation blocks the task, ask the user to handle it in the same visible window. Then perform a fresh read with the same Run, Session, and Profile. Continue to business actions only after page evidence confirms the correct tab and the required authentication state.

4. Observe → Decide → Act → Verify

1. Observe: Obtain a fresh managed snapshot and use only refs from the current page generation. Treat each relevant SiteMap entry as a route hypothesis that still requires page validation.

2. Decide: Before constructing a Plan, define the target page state for this turn, the basis for choosing stock or Replay, the inputs, the effect/confirmation boundary, and the expected success signal. Task understanding, page comparison, or business judgment already completed by the Agent may produce a Procedure input. The Procedure consumes those decided inputs for a mechanical continuation; it does not choose the business object or next action again.

3. Act: When a behavior being considered for learning contains semantic options that may vary in the future, prefer interacting with semantic controls that preserve the chain from call input to page target/action to a positive terminal state. Call inputs may come from the task, a repeatable derivation, a site option, or the Agent's current judgment. Site options and Agent judgments remain eligible even when they do not appear literally in the original task, but parameterize them rather than freezing the current literal. Treat a shortcut that compresses option semantics into an opaque URL or script as Procedure material only when evidence proves a stable mapping from inputs to arguments, or when future consumers inherently call the same fixed entry point.

   Set observe_after explicitly under the Evoui Plan. Use call:null for an ordinary action. When the action may become part of a future Procedure or its learning value must be explicitly excluded, first read Learning Annotation, then set call.

4. Verify: Prove the result with the URL, text, control state, or fresh snapshot selected during Decide; process success is not business success. A behavior considered for learning must also preserve evidence of a recognizable entry point, the actual action, and a positive terminal state. Otherwise, select no_write after Finish.

   When the expected success signal is missing, treat the outcome as unknown and stop redispatching the same action. First perform a fresh read on the exact binding and Session. Use the tab list, URL, title, and page features to confirm the active page identity. If it does not match, switch to the target tab and obtain a fresh snapshot; if it matches, still relocate the semantic control from a fresh snapshot. Only after page evidence proves that the action did not take effect and repeating it is safe, return to Decide and dispatch it once more. For submissions, creations, sends, purchases, deletions, or toggles that may already have mutated state, check the result first. Only after page identity and target freshness are confirmed and the action still fails, diagnose visibility, disabled state, overlays, or iframes. Do not use coordinates, scripts, or private page interfaces to recover page context that has not yet been confirmed.

After the page changes, Observe again. When a Plan returns a code that requires confirmation, a fresh read, a new decision, or a stop, follow the Evoui Plan branch. End each loop turn with page evidence that proves the target state or with an explicit handoff or stop outcome.