The agent that turns websites into APIs!
"""Helpers for agent-browser provider: bootstrap + prompt context.
Prefer a globally installed ``agent-browser`` on ``PATH``. If missing, run
``npm install -g <pin>`` (from config / ``RAE_AGENT_BROWSER_PACKAGE``) so the daemon
pairs consistently with Chromium; notify the operator when Reverse API Engineer performs
that install. Fall back to ``npx -y <pin>`` only when npm/global install cannot run.
Models invoke the CLI from shell tooling (for example Bash on Claude SDK runs).
"""
from __future__ import annotations
import os
import shlex
import shutil
import subprocess
import sys
from dataclasses import dataclass
from typing import Any
from rich.console import Console
from .runtime_commands import resolve_windows_command
from .utils import get_config_path
_AGENT_BROWSER_TOOLS = frozenset(
{
"Read",
"Write",
"Edit",
"Glob",
"Grep",
"Bash",
"WebFetch",
"WebSearch",
"AskUserQuestion",
},
)
_SHELL_INVOKER: str | None = None
@dataclass(frozen=True)
class AgentBrowserSetup:
"""Outcome of resolving the CLI before an agent-browser session."""
error: str | None = None
notices: tuple[str, ...] = ()
@property
def ok(self) -> bool:
return self.error is None
def reset_agent_browser_setup_cache() -> None:
"""Clear cached shell invocation (for tests only)."""
global _SHELL_INVOKER
_SHELL_INVOKER = None
def print_agent_browser_setup_notices(console: Console, setup: AgentBrowserSetup) -> None:
"""Emit install/fallback chatter before streaming."""
for note in setup.notices:
console.print(f"\n[yellow]agent-browser[/yellow]: {note}")
def _config_manager_snapshot() -> dict[str, Any]:
"""Load config defaults merged with ~/.reverse-api/config.json."""
try:
from .config import ConfigManager
cm = ConfigManager(get_config_path())
return cm.config.copy()
except Exception:
return {}
def agent_browser_npx_package() -> str:
"""Pinned npm specifier passed to ``npm install -g`` / ``npx -y`` (``RAE_AGENT_BROWSER_PACKAGE``)."""
env = os.environ.get("RAE_AGENT_BROWSER_PACKAGE", "").strip()
if env:
return env
cfg = _config_manager_snapshot()
return str(cfg.get("agent_browser_npx_package") or "agent-browser@0")
def agent_browser_extra_notes() -> str:
"""Optional user guidance; env ``RAE_AGENT_BROWSER_NOTES`` overrides config."""
env = os.environ.get("RAE_AGENT_BROWSER_NOTES", "").strip()
if env:
return env
return (_config_manager_snapshot().get("agent_browser_notes") or "").strip()
def _probe_help_argv(argv_without_help: list[str]) -> str | None:
argv = [*argv_without_help, "--help"]
try:
if sys.platform == "win32":
argv = resolve_windows_command(argv)
proc = subprocess.run(
argv,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=240,
check=False,
)
except subprocess.TimeoutExpired:
return f"timed out running `{shlex.join(argv_without_help)} --help`."
except (OSError, ValueError) as e:
return f"failed subprocess `{shlex.join(argv_without_help)}`: {e}"
stdout = (proc.stdout or "").strip()
stderr = (proc.stderr or "").strip()
if proc.returncode == 0:
return None
blob = stderr or stdout or "(no output)"
blob = blob[:1600]
return (
f"`{shlex.join(argv_without_help)} --help` failed with exit "
f"{proc.returncode}. Output (truncated): {blob}"
)
def agent_browser_shell_invoker() -> str:
"""Shell command prefix embedded in prompts (requires prior successful ``ensure_*`` unless testing)."""
global _SHELL_INVOKER
if _SHELL_INVOKER is not None:
return _SHELL_INVOKER
pkg = agent_browser_npx_package()
return shlex.join(["npx", "-y", pkg])
def _finalize_npx_invoker(notices: list[str]) -> AgentBrowserSetup:
global _SHELL_INVOKER
if shutil.which("npx") is None:
return AgentBrowserSetup(
error=(
"npx not found on PATH. Install agent-browser globally "
"`npm install -g agent-browser`, or fix PATH so npm's global bin is visible."
),
notices=tuple(notices),
)
pkg = agent_browser_npx_package()
err = _probe_help_argv(["npx", "-y", pkg])
if err:
hint = "`RAE_AGENT_BROWSER_PACKAGE` or config `agent_browser_npx_package` can pin/coerce versions."
return AgentBrowserSetup(
error=f"{err} Adjust {hint}",
notices=tuple(notices),
)
inv = shlex.join(["npx", "-y", pkg])
_SHELL_INVOKER = inv
return AgentBrowserSetup(notices=tuple(notices))
def check_agent_browser_runtime() -> AgentBrowserSetup:
"""Validate agent-browser readiness without installing packages or caching invokers.
Used by ``agent --dry-run`` so validation stays read-only.
"""
notices: list[str] = []
if shutil.which("agent-browser"):
err = _probe_help_argv(["agent-browser"])
if err:
return AgentBrowserSetup(error=err, notices=tuple(notices))
return AgentBrowserSetup(
notices=("global `agent-browser` on PATH (`--help` OK)",),
)
pkg = agent_browser_npx_package()
have_npm = shutil.which("npm") is not None
have_npx = shutil.which("npx") is not None
if not have_npm and not have_npx:
return AgentBrowserSetup(
error=(
"`agent-browser` not on PATH and neither npm nor npx is available to "
"install or run the pinned package."
),
)
if shutil.which("node") is None:
return AgentBrowserSetup(
error="node not found in PATH (needed to install/run agent-browser when the binary is missing).",
)
if have_npm:
notices.append(f"live run would `npm install -g {pkg}` when the binary is missing")
if have_npx:
notices.append(f"live run can fall back to `npx -y {pkg}` if global install fails")
return AgentBrowserSetup(notices=tuple(notices))
def ensure_agent_browser_runtime() -> AgentBrowserSetup:
"""Resolve ``agent-browser`` on PATH or install globally, else fall back to ``npx -y``.
Successful runs stash the shell snippet for ``agent_browser_prompt_fields``.
"""
global _SHELL_INVOKER
notices: list[str] = []
_SHELL_INVOKER = None
if shutil.which("agent-browser"):
err = _probe_help_argv(["agent-browser"])
if err:
return AgentBrowserSetup(error=err, notices=tuple(notices))
_SHELL_INVOKER = "agent-browser"
return AgentBrowserSetup(notices=tuple(notices))
if shutil.which("node") is None:
return AgentBrowserSetup(error="node not found in PATH (needed to install/run agent-browser).")
npm = shutil.which("npm")
pkg = agent_browser_npx_package()
if npm is None:
notices.append("npm was not found on PATH; falling back to `npx -y …` instead of global install.")
return _finalize_npx_invoker(notices)
try:
proc = subprocess.run(
resolve_windows_command([npm, "install", "-g", "--yes", pkg]),
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=600,
check=False,
env={**os.environ, "CI": "1"},
)
except subprocess.TimeoutExpired:
notices.append("`npm install -g …` timed out; falling back to `npx -y …` for this session.")
return _finalize_npx_invoker(notices)
except (OSError, ValueError) as e:
notices.append(f"Could not spawn npm globally ({e}); falling back to `npx -y …`.")
return _finalize_npx_invoker(notices)
if proc.returncode != 0:
blob = (proc.stderr or proc.stdout or "").strip()
notices.append(
"`npm install -g …` returned a non-zero status (showing truncated output "
f"below); falling back to `npx -y …`. Output: {(blob[:800] + '…') if len(blob) > 800 else blob or '(empty)'}"
)
return _finalize_npx_invoker(notices)
notices.append(
f'Installed upstream agent-browser with `npm install -g {pkg}`. '
'If Chromium is missing, run `agent-browser install` once (add `--with-deps` on trimmed Linux VMs). '
'Reuse this global install across runs for consistent browser pairing.'
)
if not shutil.which("agent-browser"):
notices.append(
"Global install finished but `agent-browser` is not on PATH; trying `npx -y …` for this session."
)
return _finalize_npx_invoker(notices)
err = _probe_help_argv(["agent-browser"])
if err:
return AgentBrowserSetup(error=err, notices=tuple(notices))
_SHELL_INVOKER = "agent-browser"
return AgentBrowserSetup(notices=tuple(notices))
def allowed_tools_agent_browser_agent_mode() -> list[str]:
"""Tool allow-list for Claude SDK runs when browsing is delegated to agent-browser."""
return sorted(_AGENT_BROWSER_TOOLS)
def agent_browser_prompt_fields(*, run_id: str, headless: bool) -> dict[str, str]:
"""Variables for ``prompts/auto/user_agent_browser.md``."""
shell = agent_browser_shell_invoker()
session = f"rae-{run_id}"
headed = (
""
if headless
else "Use the global `--headed` flag on subcommands that show a window when you need "
"a visible browser (local debugging only).\n\n"
)
notes = agent_browser_extra_notes()
notes_block = ""
if notes:
notes_block = f"\n## Extra operator notes (from config or RAE_AGENT_BROWSER_NOTES)\n\n{notes}\n"
return {
"agent_browser_shell": shell,
"agent_browser_npx_package": agent_browser_npx_package(),
"agent_browser_session": session,
"agent_browser_headed_hint": headed,
"agent_browser_notes_block": notes_block,
}