silicon-browser 0.1.0__py3-none-any.whl

silicon_browser/__init__.py

@@ -0,0 +1,3 @@
+"""Silicon Browser — terminal-native browser CLI for AI agents, powered by Steel."""
+
+__version__ = "0.1.0"

silicon_browser/browser.py

@@ -0,0 +1,92 @@
+"""Playwright connection over Steel's remote CDP endpoint.
+
+Every command opens a short-lived CDP connection to the (already running) Steel
+browser, does its work, persists any state changes, and disconnects. Closing the
+Playwright connection does **not** end the Steel session — that only happens on
+an explicit ``close``/``release`` or when the session timeout elapses.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Iterator
+
+from playwright.sync_api import Browser, BrowserContext, Page, sync_playwright
+
+from .config import get_api_key, get_connect_url
+from .state import SessionState
+
+NAV_TIMEOUT_MS = 30_000
+ACTION_TIMEOUT_MS = 15_000
+
+
+class BrowserError(Exception):
+    """Raised when the remote browser cannot be reached or driven."""
+
+
+@dataclass
+class Connection:
+    browser: Browser
+    context: BrowserContext
+    page: Page
+    state: SessionState
+
+
+def _cdp_url(state: SessionState) -> str:
+    key = get_api_key()
+    base = state.websocket_url
+    override = get_connect_url()
+    if override:
+        # Replace just the scheme+host for self-hosted Steel, keep the query.
+        from urllib.parse import urlparse, urlunparse
+
+        ws = urlparse(base)
+        ov = urlparse(override)
+        base = urlunparse((ov.scheme or ws.scheme, ov.netloc, ws.path,
+                           ws.params, ws.query, ws.fragment))
+    sep = "&" if "?" in base else "?"
+    return f"{base}{sep}apiKey={key}"
+
+
+def _active_page(context: BrowserContext, state: SessionState) -> Page:
+    pages = context.pages
+    if not pages:
+        return context.new_page()
+    idx = state.active_tab
+    if idx < 0 or idx >= len(pages):
+        idx = len(pages) - 1
+        state.active_tab = idx
+    return pages[idx]
+
+
+@contextmanager
+def connect(state: SessionState) -> Iterator[Connection]:
+    """Connect to the session's remote browser and yield the active page.
+
+    State is saved automatically on clean exit.
+    """
+    with sync_playwright() as p:
+        try:
+            browser = p.chromium.connect_over_cdp(_cdp_url(state))
+        except Exception as exc:  # noqa: BLE001
+            raise BrowserError(
+                f"Could not connect to the Steel session ({state.session_id}). "
+                "It may have expired — run `silicon-browser open <url>` to start a "
+                f"new one.\n  underlying error: {exc}"
+            ) from exc
+
+        contexts = browser.contexts
+        context = contexts[0] if contexts else browser.new_context()
+        # Fail loudly rather than hang forever on a stuck navigation/action.
+        context.set_default_navigation_timeout(NAV_TIMEOUT_MS)
+        context.set_default_timeout(ACTION_TIMEOUT_MS)
+        page = _active_page(context, state)
+        try:
+            yield Connection(browser=browser, context=context, page=page, state=state)
+            state.save()
+        finally:
+            try:
+                browser.close()
+            except Exception:  # noqa: BLE001
+                pass

silicon_browser/cli.py

@@ -0,0 +1,243 @@
+"""Silicon Browser command-line interface (Typer)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from . import __version__
+from .config import ConfigError, Options
+from .output import fail
+from .commands import inspect as inspect_cmds
+from .commands import interact as interact_cmds
+from .commands import manage as manage_cmds
+from .commands import navigate as navigate_cmds
+from .commands import share as share_cmd
+from .commands import tabs as tab_cmds
+
+app = typer.Typer(
+    name="silicon-browser",
+    help="Terminal-native browser for AI agents, powered by Steel Browser.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+get_app = typer.Typer(help="Extract data from an element by @ref.", no_args_is_help=True)
+tab_app = typer.Typer(help="Manage browser tabs.", no_args_is_help=True)
+profile_app = typer.Typer(help="Manage persistent profiles.", no_args_is_help=True)
+app.add_typer(get_app, name="get")
+app.add_typer(tab_app, name="tab")
+app.add_typer(profile_app, name="profile")
+
+
+def _opts(ctx: typer.Context) -> Options:
+    return ctx.obj  # set in the root callback
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(f"silicon-browser {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    session: str = typer.Option("default", "--session", "-s", help="Named session."),
+    profile: Optional[str] = typer.Option(None, "--profile", help="Persistent profile."),
+    incognito: bool = typer.Option(False, "--incognito", help="Ephemeral session."),
+    proxy: Optional[str] = typer.Option(None, "--proxy", help="Proxy URL."),
+    user_agent: Optional[str] = typer.Option(None, "--user-agent", help="Custom UA."),
+    solve_captcha: bool = typer.Option(False, "--solve-captcha", help="Auto-solve CAPTCHAs."),
+    _v: bool = typer.Option(False, "--version", callback=_version, is_eager=True),
+) -> None:
+    ctx.obj = Options(
+        session=session,
+        profile=profile,
+        incognito=incognito,
+        proxy=proxy,
+        user_agent=user_agent,
+        solve_captcha=solve_captcha,
+    )
+
+
+# --- navigation / lifecycle ------------------------------------------------
+@app.command("open")
+def open_(ctx: typer.Context, url: str = typer.Argument(..., help="URL to open.")):
+    """Navigate to a URL (starts a session if none is active)."""
+    navigate_cmds.cmd_open(_opts(ctx), url)
+
+
+@app.command("close")
+def close(ctx: typer.Context):
+    """Close the session and release the Steel browser."""
+    navigate_cmds.cmd_close(_opts(ctx))
+
+
+@app.command("install")
+def install(ctx: typer.Context):
+    """Verify Steel credentials and connectivity (no local Chrome needed)."""
+    navigate_cmds.cmd_install(_opts(ctx))
+
+
+# --- inspection ------------------------------------------------------------
+@app.command("snapshot")
+def snapshot(
+    ctx: typer.Context,
+    interactive: bool = typer.Option(False, "-i", "--interactive", help="Interactive elements only."),
+    json_out: bool = typer.Option(False, "--json", help="Emit JSON."),
+):
+    """Capture the accessibility tree with @refs."""
+    inspect_cmds.cmd_snapshot(_opts(ctx), interactive, json_out)
+
+
+@app.command("screenshot")
+def screenshot(
+    ctx: typer.Context,
+    path: Optional[str] = typer.Argument(None, help="Output path (default: auto)."),
+    full_page: bool = typer.Option(False, "--full-page", help="Capture full page."),
+):
+    """Capture a screenshot."""
+    inspect_cmds.cmd_screenshot(_opts(ctx), path, full_page)
+
+
+@app.command("evaluate")
+def evaluate(ctx: typer.Context, expression: str = typer.Argument(..., help="JS expression.")):
+    """Execute JavaScript in the page and print the result."""
+    inspect_cmds.cmd_evaluate(_opts(ctx), expression)
+
+
+@get_app.command("text")
+def get_text(ctx: typer.Context, ref: str):
+    """Get an element's text."""
+    inspect_cmds.cmd_get_text(_opts(ctx), ref)
+
+
+@get_app.command("html")
+def get_html(ctx: typer.Context, ref: str):
+    """Get an element's inner HTML."""
+    inspect_cmds.cmd_get_html(_opts(ctx), ref)
+
+
+@get_app.command("value")
+def get_value(ctx: typer.Context, ref: str):
+    """Get an input element's value."""
+    inspect_cmds.cmd_get_value(_opts(ctx), ref)
+
+
+# --- interaction -----------------------------------------------------------
+@app.command("click")
+def click(ctx: typer.Context, ref: str):
+    """Click an element by @ref."""
+    interact_cmds.cmd_click(_opts(ctx), ref)
+
+
+@app.command("fill")
+def fill(ctx: typer.Context, ref: str, text: str):
+    """Fill an input by @ref."""
+    interact_cmds.cmd_fill(_opts(ctx), ref, text)
+
+
+@app.command("type")
+def type_(
+    ctx: typer.Context,
+    text: str,
+    delay: float = typer.Option(0.0, "--delay", help="Per-keystroke delay (ms)."),
+):
+    """Type text at the keyboard level."""
+    interact_cmds.cmd_type(_opts(ctx), text, delay)
+
+
+@app.command("select")
+def select(ctx: typer.Context, ref: str, value: str):
+    """Select a dropdown option by @ref."""
+    interact_cmds.cmd_select(_opts(ctx), ref, value)
+
+
+@app.command("hover")
+def hover(ctx: typer.Context, ref: str):
+    """Hover over an element by @ref."""
+    interact_cmds.cmd_hover(_opts(ctx), ref)
+
+
+@app.command("scroll")
+def scroll(
+    ctx: typer.Context,
+    direction: str = typer.Argument("down", help="down | up | top | bottom."),
+    amount: Optional[int] = typer.Option(None, "--amount", help="Pixels for up/down."),
+):
+    """Scroll the page."""
+    interact_cmds.cmd_scroll(_opts(ctx), direction, amount)
+
+
+# --- tabs ------------------------------------------------------------------
+@app.command("tabs")
+def tabs(ctx: typer.Context):
+    """List open tabs."""
+    tab_cmds.cmd_tabs(_opts(ctx))
+
+
+@tab_app.command("new")
+def tab_new(ctx: typer.Context, url: Optional[str] = typer.Argument(None)):
+    """Open a new tab (optionally at a URL)."""
+    tab_cmds.cmd_tab_new(_opts(ctx), url)
+
+
+@tab_app.command("select")
+def tab_select(ctx: typer.Context, index: int):
+    """Switch to a tab by index."""
+    tab_cmds.cmd_tab_select(_opts(ctx), index)
+
+
+# --- remote access link ----------------------------------------------------
+@app.command("share")
+def share(
+    ctx: typer.Context,
+    expiry: Optional[int] = typer.Option(None, "--expiry", "-e", help="Minutes (default 60)."),
+    view_only: bool = typer.Option(False, "--view-only", help="Disable take-control."),
+    new: bool = typer.Option(False, "--new", help="Force a fresh session for this link."),
+):
+    """Generate a remote browser access link with an expiry (default 60 min)."""
+    share_cmd.cmd_share(_opts(ctx), expiry, view_only, new)
+
+
+# --- management ------------------------------------------------------------
+@app.command("status")
+def status(ctx: typer.Context):
+    """Show the current session's status and expiry."""
+    manage_cmds.cmd_status(_opts(ctx))
+
+
+@app.command("sessions")
+def sessions(ctx: typer.Context):
+    """List local sessions and whether they're still live."""
+    manage_cmds.cmd_sessions_list(_opts(ctx))
+
+
+@profile_app.command("list")
+def profile_list(ctx: typer.Context):
+    """List saved profiles."""
+    manage_cmds.cmd_profile_list(_opts(ctx))
+
+
+@profile_app.command("save")
+def profile_save(ctx: typer.Context, name: str):
+    """Save the current session's context into a profile."""
+    manage_cmds.cmd_profile_save(_opts(ctx), name)
+
+
+@profile_app.command("delete")
+def profile_delete(ctx: typer.Context, name: str):
+    """Delete a saved profile."""
+    manage_cmds.cmd_profile_delete(_opts(ctx), name)
+
+
+def run() -> None:
+    try:
+        app()
+    except ConfigError as exc:
+        fail(str(exc))
+
+
+if __name__ == "__main__":
+    run()

silicon_browser/commands/__init__.py

@@ -0,0 +1 @@
+"""Command implementations for the Silicon Browser CLI."""

silicon_browser/commands/_common.py

@@ -0,0 +1,31 @@
+"""Helpers shared across command implementations."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Iterator
+
+from ..browser import Connection, connect
+from ..config import Options
+from ..output import fail
+from ..session import ensure_session, get_live_state
+
+
+@contextmanager
+def page_for(opts: Options, *, create: bool = False) -> Iterator[Connection]:
+    """Yield a live :class:`Connection` for the requested session.
+
+    With ``create=True`` a session is started if none exists (used by ``open``).
+    Otherwise a missing/expired session is a hard error with guidance.
+    """
+    if create:
+        state = ensure_session(opts)
+    else:
+        state = get_live_state(opts.session)
+        if state is None:
+            fail(
+                f"No active session named '{opts.session}'. "
+                "Start one with `silicon-browser open <url>`."
+            )
+    with connect(state) as conn:
+        yield conn

silicon_browser/commands/inspect.py

@@ -0,0 +1,88 @@
+"""Inspection commands: snapshot, get text/html/value, screenshot, evaluate."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..config import SCREENSHOTS_DIR, Options, ensure_dirs
+from ..output import console, fail, info, render_snapshot, success
+from ..refs import RefError, resolve, take_snapshot
+from ._common import page_for
+
+
+def cmd_snapshot(opts: Options, interactive_only: bool, as_json: bool) -> None:
+    with page_for(opts) as conn:
+        nodes = take_snapshot(conn.page, conn.state, interactive_only)
+    if as_json:
+        console.print_json(json.dumps(nodes))
+    else:
+        render_snapshot(nodes)
+        info(f"\n[dim]{len(nodes)} element(s). Use @ref with click/fill/get.[/dim]")
+
+
+def _get_one(opts: Options, kind: str, ref: str) -> None:
+    with page_for(opts) as conn:
+        try:
+            loc = resolve(conn.page, conn.state, ref)
+        except RefError as exc:
+            fail(str(exc))
+            return
+        if kind == "text":
+            out = loc.inner_text()
+        elif kind == "html":
+            out = loc.inner_html()
+        elif kind == "value":
+            out = loc.input_value()
+        else:  # pragma: no cover - guarded by CLI
+            fail(f"Unknown get target '{kind}'.")
+            return
+    console.print(out)
+
+
+def cmd_get_text(opts: Options, ref: str) -> None:
+    _get_one(opts, "text", ref)
+
+
+def cmd_get_html(opts: Options, ref: str) -> None:
+    _get_one(opts, "html", ref)
+
+
+def cmd_get_value(opts: Options, ref: str) -> None:
+    _get_one(opts, "value", ref)
+
+
+def cmd_screenshot(opts: Options, path: str | None, full_page: bool) -> None:
+    ensure_dirs()
+    if path:
+        out_path = Path(path).expanduser()
+    else:
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+        out_path = SCREENSHOTS_DIR / f"{opts.session}-{stamp}.png"
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with page_for(opts) as conn:
+        conn.page.screenshot(path=str(out_path), full_page=full_page)
+    success(f"Saved screenshot → [bold]{out_path}[/bold]")
+
+
+def _evaluate(page, expression: str):
+    """Evaluate JS, falling back to a function body for multi-statement code."""
+    try:
+        return page.evaluate(expression)
+    except Exception as exc:  # noqa: BLE001
+        msg = str(exc)
+        if "SyntaxError" in msg or "Illegal return" in msg or "Unexpected" in msg:
+            return page.evaluate(f"() => {{ {expression} }}")
+        raise
+
+
+def cmd_evaluate(opts: Options, expression: str) -> None:
+    with page_for(opts) as conn:
+        result = _evaluate(conn.page, expression)
+    if result is None:
+        info("[dim]undefined[/dim]")
+    elif isinstance(result, (dict, list)):
+        console.print_json(json.dumps(result, default=str))
+    else:
+        console.print(str(result))

silicon_browser/commands/interact.py

@@ -0,0 +1,67 @@
+"""Interaction commands: click, fill, type, select, hover, scroll."""
+
+from __future__ import annotations
+
+from ..config import Options
+from ..output import fail, success
+from ..refs import RefError, resolve
+from ._common import page_for
+
+
+def _resolve_or_fail(conn, ref: str):
+    try:
+        return resolve(conn.page, conn.state, ref)
+    except RefError as exc:
+        fail(str(exc))
+        raise SystemExit(1)
+
+
+def cmd_click(opts: Options, ref: str) -> None:
+    with page_for(opts) as conn:
+        _resolve_or_fail(conn, ref).click()
+    success(f"Clicked @{ref.lstrip('@')}")
+
+
+def cmd_fill(opts: Options, ref: str, text: str) -> None:
+    with page_for(opts) as conn:
+        _resolve_or_fail(conn, ref).fill(text)
+    success(f"Filled @{ref.lstrip('@')}")
+
+
+def cmd_type(opts: Options, text: str, delay: float) -> None:
+    with page_for(opts) as conn:
+        conn.page.keyboard.type(text, delay=delay)
+    success(f"Typed {len(text)} character(s)")
+
+
+def cmd_select(opts: Options, ref: str, value: str) -> None:
+    with page_for(opts) as conn:
+        _resolve_or_fail(conn, ref).select_option(value)
+    success(f"Selected '{value}' on @{ref.lstrip('@')}")
+
+
+def cmd_hover(opts: Options, ref: str) -> None:
+    with page_for(opts) as conn:
+        _resolve_or_fail(conn, ref).hover()
+    success(f"Hovered @{ref.lstrip('@')}")
+
+
+_AMOUNTS = {"down": 600, "up": -600, "top": None, "bottom": None}
+
+
+def cmd_scroll(opts: Options, direction: str, amount: int | None) -> None:
+    direction = direction.lower()
+    with page_for(opts) as conn:
+        if direction == "top":
+            conn.page.evaluate("window.scrollTo(0, 0)")
+        elif direction == "bottom":
+            conn.page.evaluate("window.scrollTo(0, document.body.scrollHeight)")
+        elif direction in ("down", "up"):
+            dy = amount if amount is not None else abs(_AMOUNTS[direction])
+            if direction == "up":
+                dy = -dy
+            conn.page.mouse.wheel(0, dy)
+        else:
+            fail("Scroll direction must be one of: down, up, top, bottom.")
+            return
+    success(f"Scrolled {direction}")

silicon_browser/commands/manage.py

@@ -0,0 +1,80 @@
+"""Auxiliary commands: status, sessions list, profile management."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from ..config import Options
+from ..output import console, fail, info, success, warn
+from ..profiles import delete_profile, list_profiles, normalize_context, save_context
+from ..session import get_live_state
+from ..state import SessionState
+from ..steel_client import get_client
+
+
+def _fmt_local(dt: datetime) -> str:
+    return dt.astimezone().strftime("%Y-%m-%d %H:%M:%S %Z")
+
+
+def cmd_status(opts: Options) -> None:
+    state = SessionState.load(opts.session)
+    if state is None:
+        info(f"No session named '{opts.session}'.")
+        return
+    info(f"[bold]Session:[/bold] {opts.session}  ([dim]{state.session_id}[/dim])")
+    if state.profile:
+        info(f"  profile: {state.profile}")
+    try:
+        remote = get_client().sessions.retrieve(state.session_id)
+        expires_at = remote.created_at + timedelta(milliseconds=remote.timeout)
+        info(f"  status:  {remote.status}")
+        info(f"  expires: {_fmt_local(expires_at)}")
+        info(f"  credits: {remote.credits_used}")
+    except Exception as exc:  # noqa: BLE001
+        warn(f"Could not reach Steel for live details: {exc}")
+    info(f"  viewer:  {state.session_viewer_url}")
+
+
+def cmd_sessions_list(opts: Options) -> None:
+    names = SessionState.list_names()
+    if not names:
+        info("No local sessions.")
+        return
+    for name in names:
+        st = SessionState.load(name)
+        if st is None:
+            continue
+        live = get_live_state(name) is not None
+        dot = "[green]●[/green]" if live else "[red]○[/red]"
+        console.print(f"{dot} [bold]{name}[/bold]  [dim]{st.session_id}[/dim]")
+
+
+def cmd_profile_list(opts: Options) -> None:
+    profiles = list_profiles()
+    if not profiles:
+        info("No saved profiles.")
+        return
+    for p in profiles:
+        console.print(f"  {p}")
+
+
+def cmd_profile_save(opts: Options, name: str) -> None:
+    """Capture the current session's context into a named profile."""
+    state = get_live_state(opts.session)
+    if state is None:
+        fail(f"No active session named '{opts.session}' to save from.")
+        return
+    try:
+        ctx = get_client().sessions.context(state.session_id)
+    except Exception as exc:  # noqa: BLE001
+        fail(f"Could not fetch session context: {exc}")
+        return
+    save_context(name, normalize_context(ctx.model_dump(exclude_none=True)))
+    success(f"Saved profile '{name}' from session '{opts.session}'.")
+
+
+def cmd_profile_delete(opts: Options, name: str) -> None:
+    if delete_profile(name):
+        success(f"Deleted profile '{name}'.")
+    else:
+        warn(f"No profile named '{name}'.")

silicon_browser/commands/navigate.py

@@ -0,0 +1,55 @@
+"""Navigation & lifecycle commands: open, close, install."""
+
+from __future__ import annotations
+
+from ..config import Options, get_api_key
+from ..output import fail, info, success, warn
+from ..session import release_session
+from ..steel_client import get_client
+from ._common import page_for
+
+
+def _normalize_url(url: str) -> str:
+    if "://" not in url and not url.startswith("about:"):
+        return "https://" + url
+    return url
+
+
+def cmd_open(opts: Options, url: str) -> None:
+    target = _normalize_url(url)
+    with page_for(opts, create=True) as conn:
+        conn.page.goto(target, wait_until="domcontentloaded")
+        title = conn.page.title()
+        final_url = conn.page.url
+    success(f"Opened [bold]{final_url}[/bold]")
+    if title:
+        info(f"  title: {title}")
+    info(f"  session: {opts.session}")
+
+
+def cmd_close(opts: Options) -> None:
+    released = release_session(opts.session)
+    if released:
+        success(f"Closed session '{opts.session}'.")
+    else:
+        warn(f"No active session named '{opts.session}'.")
+
+
+def cmd_install(opts: Options) -> None:
+    """No Chrome to download with Steel — verify connectivity & credentials."""
+    try:
+        key = get_api_key()
+    except Exception as exc:  # ConfigError
+        fail(str(exc))
+        return
+    info("Verifying Steel credentials…")
+    try:
+        client = get_client()
+        # A cheap authenticated call to confirm the key works.
+        client.sessions.list()
+    except Exception as exc:  # noqa: BLE001
+        fail(f"Could not authenticate with Steel: {exc}")
+        return
+    success("Steel is reachable and your API key works.")
+    info(f"  key: …{key[-6:]}")
+    info("You're ready: `silicon-browser open example.com`")