browser-control-and-automation-cli 0.1.1.dev3__py3-none-any.whl

browser_cli/task_runtime/entrypoint.py

@@ -0,0 +1,110 @@
+"""Shared task loading, validation, and execution helpers."""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import json
+from collections.abc import Callable
+from contextlib import nullcontext, redirect_stderr, redirect_stdout
+from pathlib import Path
+from typing import Any
+
+from browser_cli.task_runtime.client import BrowserCliTaskClient
+from browser_cli.task_runtime.errors import TaskEntrypointError, TaskMetadataError
+from browser_cli.task_runtime.flow import Flow
+from browser_cli.task_runtime.models import FlowContext, validate_task_metadata
+
+
+def parse_input_overrides(pairs: list[str] | None, inputs_json: str | None) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    if inputs_json:
+        payload = json.loads(inputs_json)
+        if not isinstance(payload, dict):
+            raise TaskMetadataError("--inputs-json must decode to a JSON object.")
+        merged.update(payload)
+    for pair in pairs or []:
+        if "=" not in pair:
+            raise TaskMetadataError(f"Invalid --set value {pair!r}; expected KEY=VALUE.")
+        key, value = pair.split("=", 1)
+        merged[key] = value
+    return merged
+
+
+def validate_task_dir(task_dir: Path) -> dict[str, Any]:
+    task_path = task_dir / "task.py"
+    meta_path = task_dir / "task.meta.json"
+    if not task_path.exists():
+        raise TaskEntrypointError(f"Task directory is missing task.py: {task_dir}")
+    if not meta_path.exists():
+        raise TaskMetadataError(f"Task directory is missing task.meta.json: {task_dir}")
+    payload = json.loads(meta_path.read_text(encoding="utf-8"))
+    validate_task_metadata(payload, source=str(meta_path))
+    load_task_entrypoint(task_path, "run")
+    return payload
+
+
+def load_task_entrypoint(task_path: Path, entrypoint: str) -> Callable[..., dict[str, Any]]:
+    spec = importlib.util.spec_from_file_location(f"browser_cli_task_{task_path.stem}", task_path)
+    if spec is None or spec.loader is None:
+        raise TaskEntrypointError(f"Could not load task module: {task_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    fn = getattr(module, entrypoint, None)
+    if fn is None or not callable(fn):
+        raise TaskEntrypointError(
+            f"Task entrypoint {entrypoint!r} is missing or not callable: {task_path}"
+        )
+    signature = inspect.signature(fn)
+    positional = [
+        param
+        for param in signature.parameters.values()
+        if param.kind
+        in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    if len(positional) < 2:
+        raise TaskEntrypointError(
+            f"Task entrypoint must accept flow and inputs parameters: {task_path}"
+        )
+    extra_required = [param for param in positional[2:] if param.default is inspect.Parameter.empty]
+    if extra_required:
+        names = ", ".join(param.name for param in extra_required)
+        raise TaskEntrypointError(
+            f"Task entrypoint has unsupported required positional parameters ({names}): {task_path}"
+        )
+    return fn
+
+
+def run_task_entrypoint(
+    *,
+    task_path: Path,
+    entrypoint: str,
+    inputs: dict[str, Any],
+    artifacts_dir: Path,
+    automation_path: Path | None = None,
+    automation_name: str | None = None,
+    client: BrowserCliTaskClient | None = None,
+    stdout_handle: Any | None = None,
+    stderr_handle: Any | None = None,
+) -> dict[str, Any]:
+    fn = load_task_entrypoint(task_path, entrypoint)
+    flow = Flow(
+        client=client or BrowserCliTaskClient(),
+        context=FlowContext(
+            task_path=task_path,
+            task_dir=task_path.parent,
+            artifacts_dir=artifacts_dir,
+            automation_path=automation_path,
+            automation_name=automation_name,
+        ),
+    )
+    if stdout_handle is None and stderr_handle is None:
+        result = fn(flow, inputs)
+    else:
+        stdout_ctx = redirect_stdout(stdout_handle) if stdout_handle is not None else nullcontext()
+        stderr_ctx = redirect_stderr(stderr_handle) if stderr_handle is not None else nullcontext()
+        with stdout_ctx, stderr_ctx:
+            result = fn(flow, inputs)
+    if not isinstance(result, dict):
+        raise TaskEntrypointError(f"Task entrypoint must return a dict: {task_path}")
+    return result

browser_cli/task_runtime/errors.py

@@ -0,0 +1,17 @@
+"""Task runtime specific errors."""
+
+from __future__ import annotations
+
+from browser_cli.errors import InvalidInputError
+
+
+class TaskRuntimeError(InvalidInputError):
+    """Raised when a task runtime contract is invalid."""
+
+
+class TaskMetadataError(InvalidInputError):
+    """Raised when task metadata does not satisfy the expected schema."""
+
+
+class TaskEntrypointError(InvalidInputError):
+    """Raised when a task module entrypoint is missing or invalid."""

browser_cli/task_runtime/flow.py

@@ -0,0 +1,171 @@
+"""Higher-level task runtime flow helpers."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from browser_cli.task_runtime.client import BrowserCliTaskClient
+from browser_cli.task_runtime.models import FlowContext, SnapshotResult
+from browser_cli.task_runtime.read import ReadResult
+
+
+class Flow:
+    def __init__(
+        self,
+        *,
+        client: BrowserCliTaskClient | None = None,
+        context: FlowContext,
+    ) -> None:
+        self.client = client or BrowserCliTaskClient()
+        self.context = context
+        self._last_snapshot: SnapshotResult | None = None
+
+    @property
+    def artifacts_dir(self) -> Path:
+        self.context.artifacts_dir.mkdir(parents=True, exist_ok=True)
+        return self.context.artifacts_dir
+
+    def open(self, url: str) -> dict[str, Any]:
+        return self.client.open(url)
+
+    def read(
+        self,
+        url: str,
+        *,
+        output_mode: str = "html",
+        scroll_bottom: bool = False,
+    ) -> ReadResult:
+        return self.client.read(url, output_mode=output_mode, scroll_bottom=scroll_bottom)
+
+    def command(self, action: str, **args: Any) -> dict[str, Any]:
+        return self.client.command(action, **args)
+
+    def search(self, query: str, *, engine: str = "duckduckgo") -> dict[str, Any]:
+        return self.client.search(query, engine=engine)
+
+    def snapshot(self, *, interactive: bool = False, full_page: bool = True) -> SnapshotResult:
+        self._last_snapshot = self.client.snapshot(interactive=interactive, full_page=full_page)
+        return self._last_snapshot
+
+    def last_snapshot(self) -> SnapshotResult:
+        if self._last_snapshot is None:
+            self._last_snapshot = self.snapshot()
+        return self._last_snapshot
+
+    def snapshot_find(self, *, role: str, name: str, nth: int = 0, refresh: bool = False) -> str:
+        snapshot = (
+            self.snapshot() if refresh or self._last_snapshot is None else self._last_snapshot
+        )
+        return snapshot.find_ref(role=role, name=name, nth=nth)
+
+    def click(self, ref: str) -> dict[str, Any]:
+        return self.client.click(ref)
+
+    def fill(self, ref: str, text: str, *, submit: bool = False) -> dict[str, Any]:
+        return self.client.fill(ref, text, submit=submit)
+
+    def select(self, ref: str, text: str) -> dict[str, Any]:
+        return self.client.select(ref, text)
+
+    def check(self, ref: str) -> dict[str, Any]:
+        return self.client.check(ref)
+
+    def uncheck(self, ref: str) -> dict[str, Any]:
+        return self.client.uncheck(ref)
+
+    def focus(self, ref: str) -> dict[str, Any]:
+        return self.client.focus(ref)
+
+    def hover(self, ref: str) -> dict[str, Any]:
+        return self.client.hover(ref)
+
+    def wait(self, seconds: float) -> dict[str, Any]:
+        return self.client.wait(seconds)
+
+    def wait_text(
+        self, text: str, *, timeout: float = 5.0, gone: bool = False, exact: bool = False
+    ) -> dict[str, Any]:
+        return self.client.wait_text(text, timeout=timeout, gone=gone, exact=exact)
+
+    def html(self) -> str:
+        return self.client.html()
+
+    def eval(self, code: str) -> Any:
+        return self.client.eval(code)
+
+    def eval_on(self, ref: str, code: str) -> Any:
+        return self.client.eval_on(ref, code)
+
+    def verify_text(self, text: str, *, exact: bool = False, timeout: float = 5.0) -> bool:
+        return bool(self.client.verify_text(text, exact=exact, timeout=timeout).get("passed"))
+
+    def verify_state(self, ref: str, state: str) -> bool:
+        return bool(self.client.verify_state(ref, state).get("passed"))
+
+    def verify_value(self, ref: str, expected: str) -> bool:
+        return bool(self.client.verify_value(ref, expected).get("passed"))
+
+    def scroll_until_stable(
+        self,
+        *,
+        max_rounds: int = 10,
+        wait_seconds: float = 2.0,
+        confirm_rounds: int = 2,
+    ) -> dict[str, Any]:
+        stable_rounds = 0
+        history: list[dict[str, Any]] = []
+        for index in range(1, max_rounds + 1):
+            before = self.eval(
+                """() => ({
+                    scrollHeight: Math.max(document.body.scrollHeight, document.documentElement.scrollHeight),
+                    scrollY: window.scrollY,
+                    viewportHeight: window.innerHeight
+                })"""
+            )
+            self.eval(
+                """() => {
+                    const h = Math.max(document.body.scrollHeight, document.documentElement.scrollHeight);
+                    window.scrollTo(0, h);
+                    return h;
+                }"""
+            )
+            self.wait(wait_seconds)
+            after = self.eval(
+                """() => ({
+                    scrollHeight: Math.max(document.body.scrollHeight, document.documentElement.scrollHeight),
+                    scrollY: window.scrollY,
+                    viewportHeight: window.innerHeight,
+                    atBottom: window.innerHeight + window.scrollY >= Math.max(document.body.scrollHeight, document.documentElement.scrollHeight) - 4
+                })"""
+            )
+            round_result = {"round": index, "before": before, "after": after}
+            history.append(round_result)
+            if after["atBottom"] and after["scrollHeight"] <= before["scrollHeight"]:
+                stable_rounds += 1
+                if stable_rounds >= confirm_rounds:
+                    return {"stabilized": True, "rounds": history}
+            else:
+                stable_rounds = 0
+        return {"stabilized": False, "rounds": history}
+
+    def write_text_artifact(self, relative_path: str, content: str) -> Path:
+        output_path = (self.artifacts_dir / relative_path).resolve()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(content, encoding="utf-8")
+        return output_path
+
+    def write_json_artifact(self, relative_path: str, payload: Any) -> Path:
+        output_path = (self.artifacts_dir / relative_path).resolve()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+        return output_path
+
+    def screenshot(self, relative_path: str, *, full_page: bool = False) -> Path:
+        output_path = (self.artifacts_dir / relative_path).resolve()
+        self.client.screenshot(str(output_path), full_page=full_page)
+        return output_path
+
+    def close(self) -> dict[str, Any]:
+        return self.client.close()

browser_cli/task_runtime/models.py

@@ -0,0 +1,97 @@
+"""Task runtime models and metadata validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from browser_cli.task_runtime.errors import TaskMetadataError
+
+REQUIRED_TASK_META_SECTIONS = (
+    "task",
+    "environment",
+    "success_path",
+    "recovery_hints",
+    "failures",
+    "knowledge",
+)
+
+
+@dataclass(slots=True, frozen=True)
+class SnapshotRef:
+    ref: str
+    role: str
+    name: str | None = None
+    nth: int | None = None
+    text_content: str | None = None
+    interactive: bool = False
+    parent_ref: str | None = None
+    frame_path: tuple[int, ...] = ()
+
+
+@dataclass(slots=True, frozen=True)
+class SnapshotResult:
+    page_id: str
+    snapshot_id: str
+    tree: str
+    refs: tuple[SnapshotRef, ...]
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> SnapshotResult:
+        refs = tuple(
+            SnapshotRef(
+                ref=str(item["ref"]),
+                role=str(item.get("role") or ""),
+                name=str(item["name"]) if item.get("name") is not None else None,
+                nth=int(item["nth"]) if item.get("nth") is not None else None,
+                text_content=str(item["text_content"])
+                if item.get("text_content") is not None
+                else None,
+                interactive=bool(item.get("interactive")),
+                parent_ref=str(item["parent_ref"]) if item.get("parent_ref") is not None else None,
+                frame_path=tuple(int(value) for value in (item.get("frame_path") or [])),
+            )
+            for item in payload.get("refs_summary", [])
+        )
+        return cls(
+            page_id=str(payload.get("page_id") or ""),
+            snapshot_id=str(payload.get("snapshot_id") or ""),
+            tree=str(payload.get("tree") or "(empty)"),
+            refs=refs,
+        )
+
+    def find_ref(self, *, role: str, name: str, nth: int = 0) -> str:
+        matches = [item.ref for item in self.refs if item.role == role and item.name == name]
+        if nth < 0 or nth >= len(matches):
+            raise TaskMetadataError(f"Could not find ref role={role!r} name={name!r} nth={nth}.")
+        return matches[nth]
+
+
+@dataclass(slots=True, frozen=True)
+class FlowContext:
+    task_path: Path
+    task_dir: Path
+    artifacts_dir: Path
+    automation_path: Path | None = None
+    automation_name: str | None = None
+
+
+def validate_task_metadata(payload: dict[str, Any], *, source: str) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        raise TaskMetadataError(f"Task metadata must be a JSON object: {source}")
+    missing = [key for key in REQUIRED_TASK_META_SECTIONS if key not in payload]
+    if missing:
+        joined = ", ".join(missing)
+        raise TaskMetadataError(f"Task metadata is missing required sections ({joined}): {source}")
+    task_section = payload.get("task")
+    if not isinstance(task_section, dict):
+        raise TaskMetadataError(f"Task metadata section 'task' must be an object: {source}")
+    for key in ("id", "name", "goal"):
+        value = task_section.get(key)
+        if not isinstance(value, str) or not value.strip():
+            raise TaskMetadataError(f"Task metadata requires non-empty task.{key}: {source}")
+    failures = payload.get("failures")
+    if not isinstance(failures, list):
+        raise TaskMetadataError(f"Task metadata section 'failures' must be an array: {source}")
+    return payload

browser_cli/task_runtime/read.py

@@ -0,0 +1,71 @@
+"""Shared one-shot read orchestration for the task runtime."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from browser_cli.daemon.client import send_command
+from browser_cli.daemon.transport import probe_socket
+from browser_cli.errors import EmptyContentError
+from browser_cli.profiles.discovery import ChromeEnvironment, discover_chrome_environment
+
+
+@dataclass(slots=True)
+class ReadRequest:
+    url: str
+    output_mode: str
+    scroll_bottom: bool = False
+
+
+@dataclass(slots=True)
+class ReadResult:
+    body: str
+    used_fallback_profile: bool = False
+    fallback_profile_dir: str | None = None
+    fallback_reason: str | None = None
+
+
+def serialize_chrome_environment(chrome_environment: ChromeEnvironment) -> dict[str, str | None]:
+    return {
+        "executable_path": (
+            str(chrome_environment.executable_path)
+            if chrome_environment.executable_path is not None
+            else None
+        ),
+        "user_data_dir": str(chrome_environment.user_data_dir),
+        "profile_directory": chrome_environment.profile_directory,
+        "profile_name": chrome_environment.profile_name,
+        "source": chrome_environment.source,
+        "fallback_reason": chrome_environment.fallback_reason,
+    }
+
+
+async def run_read_request(
+    request: ReadRequest,
+    *,
+    chrome_environment: ChromeEnvironment | None = None,
+) -> ReadResult:
+    command_args = {
+        "url": request.url,
+        "output_mode": request.output_mode,
+        "scroll_bottom": request.scroll_bottom,
+    }
+    if not probe_socket():
+        resolved_environment = chrome_environment or discover_chrome_environment()
+        command_args["chrome_environment"] = serialize_chrome_environment(resolved_environment)
+    payload = await asyncio.to_thread(send_command, "read-page", command_args)
+    body = str(payload.get("data", {}).get("body") or "")
+    if not body.strip():
+        raise EmptyContentError()
+    used_fallback = bool(payload.get("data", {}).get("used_fallback_profile"))
+    return ReadResult(
+        body=body,
+        used_fallback_profile=used_fallback,
+        fallback_profile_dir=(
+            str(payload.get("data", {}).get("fallback_profile_dir"))
+            if used_fallback and payload.get("data", {}).get("fallback_profile_dir")
+            else None
+        ),
+        fallback_reason=str(payload.get("data", {}).get("fallback_reason") or "") or None,
+    )

browser_cli/task_runtime/templates.py

@@ -0,0 +1,58 @@
+"""Canonical task templates and example catalog."""
+
+from __future__ import annotations
+
+TASK_TEMPLATE_FILES: dict[str, str] = {
+    "task.py": """from __future__ import annotations
+
+
+def run(flow, inputs):
+    url = str(inputs.get("url") or "https://example.com")
+    flow.open(url)
+    snapshot = flow.snapshot()
+    return {"ok": True, "url": url, "snapshot": snapshot.tree}
+""",
+    "task.meta.json": """{
+  "task": {
+    "id": "my_task",
+    "name": "My Task",
+    "goal": "Describe the task goal"
+  },
+  "environment": {},
+  "success_path": {},
+  "recovery_hints": {},
+  "failures": [],
+  "knowledge": {}
+}
+""",
+    "automation.toml": """[automation]
+id = "my_task"
+name = "My Task"
+
+[task]
+path = "task.py"
+meta_path = "task.meta.json"
+entrypoint = "run"
+
+[inputs]
+
+[schedule]
+mode = "manual"
+timezone = "UTC"
+""",
+}
+
+EXAMPLE_CATALOG: tuple[tuple[str, str], ...] = (
+    ("interactive_reveal_capture", "Capture progressively revealed content."),
+    ("lazy_scroll_capture", "Scroll and capture lazy-loaded pages."),
+    ("douyin_video_download", "Download a Douyin video via the browser-minted detail flow."),
+)
+
+
+def render_template_bundle() -> str:
+    parts: list[str] = []
+    for name, body in TASK_TEMPLATE_FILES.items():
+        parts.append(f"=== {name} ===")
+        parts.append(body.rstrip())
+        parts.append("")
+    return "\n".join(parts).rstrip() + "\n"