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

browser_cli/agent_scope/__init__.py

@@ -0,0 +1,14 @@
+"""Agent visibility-domain helpers."""
+
+from __future__ import annotations
+
+import os
+
+from browser_cli.constants import DEFAULT_PUBLIC_AGENT_ID
+
+AGENT_ID_ENV = "X_AGENT_ID"
+
+
+def resolve_agent_id() -> str:
+    raw_value = os.environ.get(AGENT_ID_ENV, "").strip()
+    return raw_value or DEFAULT_PUBLIC_AGENT_ID

browser_cli/automation/__init__.py

@@ -0,0 +1,11 @@
+"""Automation helpers."""
+
+from browser_cli.automation.loader import AutomationManifest, load_automation_manifest
+from browser_cli.automation.publisher import PublishedAutomation, publish_task_dir
+
+__all__ = [
+    "AutomationManifest",
+    "PublishedAutomation",
+    "load_automation_manifest",
+    "publish_task_dir",
+]

browser_cli/automation/api/__init__.py

@@ -0,0 +1,5 @@
+"""automation service API helpers."""
+
+from browser_cli.automation.api.server import AutomationHttpServer, AutomationRequestHandler
+
+__all__ = ["AutomationHttpServer", "AutomationRequestHandler"]

browser_cli/automation/api/server.py

@@ -0,0 +1,321 @@
+"""Local HTTP API for automation service."""
+
+from __future__ import annotations
+
+import json
+import threading
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import urlparse
+
+from browser_cli.automation.loader import load_automation_manifest
+from browser_cli.automation.models import PersistedAutomationDefinition
+from browser_cli.automation.projections import (
+    manifest_to_persisted_definition,
+    payload_to_persisted_definition,
+    persisted_definition_to_config_payload,
+    persisted_definition_to_manifest_toml,
+)
+from browser_cli.automation.web import render_index_html
+from browser_cli.errors import BrowserCliError, InvalidInputError
+
+
+class AutomationHttpServer(ThreadingHTTPServer):
+    def __init__(self, server_address, request_handler_class, runtime) -> None:
+        super().__init__(server_address, request_handler_class)
+        self.runtime = runtime
+
+
+class AutomationRequestHandler(BaseHTTPRequestHandler):
+    server: AutomationHttpServer
+
+    def do_GET(self) -> None:  # noqa: N802
+        self._handle("GET")
+
+    def do_POST(self) -> None:  # noqa: N802
+        self._handle("POST")
+
+    def do_PUT(self) -> None:  # noqa: N802
+        self._handle("PUT")
+
+    def log_message(self, _format: str, *_args) -> None:
+        return
+
+    def _handle(self, method: str) -> None:
+        parsed = urlparse(self.path)
+        path = parsed.path
+        try:
+            if path == "/":
+                self._send_html(render_index_html())
+                return
+            if path == "/api/service/status":
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": self.server.runtime.status_payload(),
+                        "meta": {},
+                    }
+                )
+                return
+            if path == "/api/service/stop" and method == "POST":
+                self.server.runtime.stop()
+                threading.Thread(target=self.server.shutdown, daemon=True).start()
+                self._send_json({"ok": True, "data": {"stopped": True}, "meta": {}})
+                return
+            if path == "/api/automations" and method == "GET":
+                automations = [
+                    self._serialize_automation(item, include_latest_run=True)
+                    for item in self.server.runtime.store.list_automations()
+                ]
+                self._send_json({"ok": True, "data": automations, "meta": {}})
+                return
+            if path == "/api/automations" and method == "POST":
+                body = self._read_json_body()
+                created = self.server.runtime.store.upsert_automation(
+                    payload_to_persisted_definition(body)
+                )
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": self._serialize_automation(created),
+                        "meta": {},
+                    },
+                    status=HTTPStatus.CREATED,
+                )
+                return
+            if path == "/api/automations/import" and method == "POST":
+                body = self._read_json_body()
+                manifest_path = str(body.get("path") or "").strip()
+                if not manifest_path:
+                    raise InvalidInputError("Automation import requires non-empty path.")
+                manifest = load_automation_manifest(manifest_path)
+                enabled = bool(body.get("enabled"))
+                automation = manifest_to_persisted_definition(manifest, enabled=enabled)
+                created = self.server.runtime.store.upsert_automation(automation)
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": self._serialize_automation(created),
+                        "meta": {},
+                    }
+                )
+                return
+            if path.startswith("/api/automations/") and path.endswith("/runs") and method == "GET":
+                automation_id = path.split("/")[3]
+                runs = [
+                    self._serialize_run(item)
+                    for item in self.server.runtime.store.list_runs(automation_id)
+                ]
+                self._send_json({"ok": True, "data": runs, "meta": {}})
+                return
+            if (
+                path.startswith("/api/automations/")
+                and path.endswith("/enable")
+                and method == "POST"
+            ):
+                automation_id = path.split("/")[3]
+                updated = self.server.runtime.store.set_enabled(automation_id, True)
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": self._serialize_automation(updated),
+                        "meta": {},
+                    }
+                )
+                return
+            if (
+                path.startswith("/api/automations/")
+                and path.endswith("/disable")
+                and method == "POST"
+            ):
+                automation_id = path.split("/")[3]
+                updated = self.server.runtime.store.set_enabled(automation_id, False)
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": self._serialize_automation(updated),
+                        "meta": {},
+                    }
+                )
+                return
+            if path.startswith("/api/automations/") and path.endswith("/run") and method == "POST":
+                automation_id = path.split("/")[3]
+                run = self.server.runtime.store.create_run(automation_id, trigger_type="manual")
+                self._send_json({"ok": True, "data": self._serialize_run(run), "meta": {}})
+                return
+            if (
+                path.startswith("/api/automations/")
+                and path.endswith("/export")
+                and method == "GET"
+            ):
+                automation_id = path.split("/")[3]
+                automation = self.server.runtime.store.get_automation(automation_id)
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": {"toml": persisted_definition_to_manifest_toml(automation)},
+                        "meta": {},
+                    }
+                )
+                return
+            if path.startswith("/api/automations/") and method == "GET":
+                automation_id = path.split("/")[3]
+                automation = self.server.runtime.store.get_automation(automation_id)
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": self._serialize_automation(automation, include_latest_run=True),
+                        "meta": {},
+                    }
+                )
+                return
+            if path.startswith("/api/automations/") and method == "PUT":
+                automation_id = path.split("/")[3]
+                payload = self._read_json_body()
+                payload["id"] = automation_id
+                updated = self.server.runtime.store.upsert_automation(
+                    payload_to_persisted_definition(payload)
+                )
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": self._serialize_automation(updated),
+                        "meta": {},
+                    }
+                )
+                return
+            if path.startswith("/api/runs/") and path.endswith("/retry") and method == "POST":
+                run_id = path.split("/")[3]
+                run = self.server.runtime.store.retry_run(run_id)
+                self._send_json({"ok": True, "data": self._serialize_run(run), "meta": {}})
+                return
+            if path.startswith("/api/runs/") and method == "GET":
+                run_id = path.split("/")[3]
+                run = self.server.runtime.store.get_run(run_id)
+                events = self.server.runtime.store.list_run_events(run_id)
+                self._send_json(
+                    {
+                        "ok": True,
+                        "data": {
+                            **self._serialize_run(run),
+                            "events": [self._serialize_event(item) for item in events],
+                            "log_text": _read_text(run.log_path),
+                        },
+                        "meta": {},
+                    }
+                )
+                return
+            self._send_json(
+                {
+                    "ok": False,
+                    "error_message": f"Not found: {path}",
+                    "error_code": "NOT_FOUND",
+                },
+                status=HTTPStatus.NOT_FOUND,
+            )
+        except KeyError as exc:
+            self._send_json(
+                {
+                    "ok": False,
+                    "error_message": f"Not found: {exc}",
+                    "error_code": "NOT_FOUND",
+                },
+                status=HTTPStatus.NOT_FOUND,
+            )
+        except Exception as exc:
+            status = (
+                HTTPStatus.BAD_REQUEST
+                if isinstance(exc, BrowserCliError | ValueError | json.JSONDecodeError)
+                else HTTPStatus.INTERNAL_SERVER_ERROR
+            )
+            self._send_json(
+                {
+                    "ok": False,
+                    "error_message": str(exc),
+                    "error_code": getattr(
+                        exc,
+                        "error_code",
+                        "INVALID_INPUT" if status == HTTPStatus.BAD_REQUEST else "INTERNAL_ERROR",
+                    ),
+                },
+                status=status,
+            )
+
+    def _send_html(self, html: str, *, status: HTTPStatus = HTTPStatus.OK) -> None:
+        body = html.encode("utf-8")
+        self.send_response(status.value)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _send_json(self, payload: dict, *, status: HTTPStatus = HTTPStatus.OK) -> None:
+        body = (json.dumps(payload, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
+        self.send_response(status.value)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _read_json_body(self) -> dict:
+        length = int(self.headers.get("Content-Length") or "0")
+        if length <= 0:
+            return {}
+        raw = self.rfile.read(length)
+        return json.loads(raw.decode("utf-8"))
+
+    def _serialize_automation(
+        self,
+        automation: PersistedAutomationDefinition,
+        *,
+        include_latest_run: bool = False,
+    ) -> dict:
+        payload = persisted_definition_to_config_payload(automation)
+        payload.update(
+            {
+                "enabled": automation.enabled,
+                "definition_status": automation.definition_status,
+                "definition_error": automation.definition_error,
+                "created_at": automation.created_at,
+                "updated_at": automation.updated_at,
+                "last_run_at": automation.last_run_at,
+                "next_run_at": automation.next_run_at,
+            }
+        )
+        if include_latest_run:
+            runs = self.server.runtime.store.list_runs(automation.id, limit=1)
+            payload["latest_run"] = self._serialize_run(runs[0]) if runs else None
+        return payload
+
+    def _serialize_run(self, run) -> dict:
+        return {
+            "run_id": run.run_id,
+            "automation_id": run.automation_id,
+            "trigger_type": run.trigger_type,
+            "status": run.status,
+            "effective_inputs": run.effective_inputs,
+            "attempt_number": run.attempt_number,
+            "queued_at": run.queued_at,
+            "started_at": run.started_at,
+            "finished_at": run.finished_at,
+            "error_code": run.error_code,
+            "error_message": run.error_message,
+            "result_json_path": str(run.result_json_path) if run.result_json_path else None,
+            "artifacts_dir": str(run.artifacts_dir) if run.artifacts_dir else None,
+            "log_path": str(run.log_path) if run.log_path else None,
+        }
+
+    def _serialize_event(self, event) -> dict:
+        return {
+            "event_type": event.event_type,
+            "message": event.message,
+            "created_at": event.created_at,
+            "payload": event.payload,
+        }
+
+
+def _read_text(path: Path | None) -> str:
+    if path is None or not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8")

browser_cli/automation/hooks.py

@@ -0,0 +1,42 @@
+"""Automation hook execution helpers."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+def run_hook_commands(
+    commands: tuple[str, ...],
+    *,
+    cwd: Path,
+    extra_env: dict[str, Any] | None = None,
+    timeout_seconds: float | None = None,
+) -> list[dict[str, Any]]:
+    results: list[dict[str, Any]] = []
+    env = os.environ.copy()
+    if extra_env:
+        env.update({key: str(value) for key, value in extra_env.items() if value is not None})
+    for command in commands:
+        completed = subprocess.run(
+            command,
+            shell=True,
+            cwd=str(cwd),
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+        )
+        results.append(
+            {
+                "command": command,
+                "returncode": completed.returncode,
+                "stdout": completed.stdout,
+                "stderr": completed.stderr,
+            }
+        )
+        if completed.returncode != 0:
+            raise RuntimeError(f"Hook failed: {command}")
+    return results

browser_cli/automation/loader.py

@@ -0,0 +1,134 @@
+"""Automation manifest loading helpers."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+from browser_cli.automation.models import (
+    AutomationHooks,
+    AutomationIdentity,
+    AutomationManifest,
+    AutomationOutputs,
+    AutomationRuntime,
+    AutomationTaskConfig,
+)
+from browser_cli.errors import InvalidInputError
+from browser_cli.task_runtime import validate_task_metadata
+
+
+def load_automation_manifest(path: str | Path) -> AutomationManifest:
+    manifest_path = Path(path).expanduser().resolve()
+    if not manifest_path.exists():
+        raise InvalidInputError(f"Automation manifest does not exist: {manifest_path}")
+    try:
+        data = tomllib.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError, ValueError) as exc:
+        raise InvalidInputError(
+            f"Automation manifest is invalid TOML: {manifest_path}: {exc}"
+        ) from exc
+    if not isinstance(data, dict):
+        raise InvalidInputError(f"Automation manifest must be a TOML object: {manifest_path}")
+
+    automation_section = _require_section(data, "automation", manifest_path)
+    task_section = _require_section(data, "task", manifest_path)
+    base_dir = manifest_path.parent
+    task_path = _resolve_relative(base_dir, _require_string(task_section, "path", manifest_path))
+    meta_path = _resolve_relative(
+        base_dir, _require_string(task_section, "meta_path", manifest_path)
+    )
+    if not task_path.exists():
+        raise InvalidInputError(f"Task file does not exist: {task_path}")
+    if not meta_path.exists():
+        raise InvalidInputError(f"Task metadata file does not exist: {meta_path}")
+    _load_task_metadata(meta_path)
+    return AutomationManifest(
+        manifest_path=manifest_path,
+        automation=AutomationIdentity(
+            id=_require_string(automation_section, "id", manifest_path),
+            name=_require_string(automation_section, "name", manifest_path),
+            description=str(automation_section.get("description") or ""),
+            version=str(automation_section.get("version") or "1"),
+        ),
+        task=AutomationTaskConfig(
+            path=task_path,
+            meta_path=meta_path,
+            entrypoint=str(task_section.get("entrypoint") or "run"),
+        ),
+        inputs=dict(data.get("inputs") or {}),
+        schedule=dict(data.get("schedule") or {}),
+        outputs=AutomationOutputs(
+            artifact_dir=_resolve_relative(
+                base_dir,
+                str((data.get("outputs") or {}).get("artifact_dir") or "artifacts"),
+            ),
+            result_json_path=(
+                _resolve_relative(
+                    base_dir, str((data.get("outputs") or {}).get("result_json_path"))
+                )
+                if (data.get("outputs") or {}).get("result_json_path")
+                else None
+            ),
+            stdout=str((data.get("outputs") or {}).get("stdout") or "json"),
+        ),
+        hooks=AutomationHooks(
+            before_run=tuple(_as_string_list((data.get("hooks") or {}).get("before_run"))),
+            after_success=tuple(_as_string_list((data.get("hooks") or {}).get("after_success"))),
+            after_failure=tuple(_as_string_list((data.get("hooks") or {}).get("after_failure"))),
+        ),
+        runtime=AutomationRuntime(
+            timeout_seconds=float((data.get("runtime") or {})["timeout_seconds"])
+            if (data.get("runtime") or {}).get("timeout_seconds") is not None
+            else None,
+            retry_attempts=int((data.get("runtime") or {}).get("retry_attempts") or 0),
+            retry_backoff_seconds=int(
+                (data.get("runtime") or {}).get("retry_backoff_seconds") or 0
+            ),
+            log_level=str((data.get("runtime") or {}).get("log_level") or "info"),
+        ),
+    )
+
+
+def _require_section(data: dict[str, Any], key: str, source: Path) -> dict[str, Any]:
+    value = data.get(key)
+    if not isinstance(value, dict):
+        raise InvalidInputError(f"Automation manifest requires a [{key}] section: {source}")
+    return value
+
+
+def _require_string(section: dict[str, Any], key: str, source: Path) -> str:
+    value = section.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise InvalidInputError(f"Automation manifest requires non-empty {key!r}: {source}")
+    return value.strip()
+
+
+def _resolve_relative(base_dir: Path, value: str) -> Path:
+    path = Path(value).expanduser()
+    if not path.is_absolute():
+        path = (base_dir / path).resolve()
+    return path
+
+
+def _as_string_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(item) for item in value if str(item).strip()]
+    return [str(value)]
+
+
+def _load_task_metadata(meta_path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(meta_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError) as exc:
+        raise InvalidInputError(f"Task metadata is invalid JSON: {meta_path}: {exc}") from exc
+    validate_task_metadata(payload, source=str(meta_path))
+    return payload

browser_cli/automation/models.py

@@ -0,0 +1,127 @@
+"""Automation manifest and service dataclasses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(slots=True, frozen=True)
+class AutomationIdentity:
+    id: str
+    name: str
+    description: str = ""
+    version: str = "0.1.0"
+
+
+@dataclass(slots=True, frozen=True)
+class AutomationTaskConfig:
+    path: Path
+    meta_path: Path
+    entrypoint: str = "run"
+
+
+@dataclass(slots=True, frozen=True)
+class AutomationOutputs:
+    artifact_dir: Path
+    result_json_path: Path | None = None
+    stdout: str = "json"
+
+
+@dataclass(slots=True, frozen=True)
+class AutomationHooks:
+    before_run: tuple[str, ...] = ()
+    after_success: tuple[str, ...] = ()
+    after_failure: tuple[str, ...] = ()
+
+
+@dataclass(slots=True, frozen=True)
+class AutomationRuntime:
+    timeout_seconds: float | None = None
+    retry_attempts: int = 0
+    retry_backoff_seconds: int = 0
+    log_level: str = "info"
+
+
+@dataclass(slots=True, frozen=True)
+class AutomationManifest:
+    manifest_path: Path
+    automation: AutomationIdentity
+    task: AutomationTaskConfig
+    inputs: dict[str, Any] = field(default_factory=dict)
+    schedule: dict[str, Any] = field(default_factory=dict)
+    outputs: AutomationOutputs = field(
+        default_factory=lambda: AutomationOutputs(artifact_dir=Path("artifacts"))
+    )
+    hooks: AutomationHooks = field(default_factory=AutomationHooks)
+    runtime: AutomationRuntime = field(default_factory=AutomationRuntime)
+
+
+@dataclass(slots=True, frozen=True)
+class PersistedAutomationDefinition:
+    id: str
+    name: str
+    task_path: Path
+    task_meta_path: Path
+    output_dir: Path
+    description: str = ""
+    version: str = "0.1.0"
+    entrypoint: str = "run"
+    enabled: bool = False
+    definition_status: str = "valid"
+    definition_error: str | None = None
+    schedule_kind: str = "manual"
+    schedule_payload: dict[str, Any] = field(default_factory=dict)
+    timezone: str = "UTC"
+    result_json_path: Path | None = None
+    stdout_mode: str = "json"
+    input_overrides: dict[str, Any] = field(default_factory=dict)
+    before_run_hooks: tuple[str, ...] = ()
+    after_success_hooks: tuple[str, ...] = ()
+    after_failure_hooks: tuple[str, ...] = ()
+    retry_attempts: int = 0
+    retry_backoff_seconds: int = 0
+    timeout_seconds: float | None = None
+    log_level: str = "info"
+    created_at: str | None = None
+    updated_at: str | None = None
+    last_run_at: str | None = None
+    next_run_at: str | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class AutomationRunRecord:
+    run_id: str
+    automation_id: str
+    trigger_type: str
+    status: str
+    effective_inputs: dict[str, Any] = field(default_factory=dict)
+    attempt_number: int = 0
+    queued_at: str | None = None
+    started_at: str | None = None
+    finished_at: str | None = None
+    error_code: str | None = None
+    error_message: str | None = None
+    result_json_path: Path | None = None
+    artifacts_dir: Path | None = None
+    log_path: Path | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class AutomationRunEvent:
+    run_id: str
+    event_type: str
+    message: str = ""
+    created_at: str | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+def manifest_to_persisted_definition(
+    manifest: AutomationManifest,
+    *,
+    enabled: bool = False,
+) -> PersistedAutomationDefinition:
+    from browser_cli.automation.projections import manifest_to_persisted_definition as _impl
+
+    return _impl(manifest, enabled=enabled)

browser_cli/automation/persistence/__init__.py

@@ -0,0 +1,5 @@
+"""automation persistence helpers."""
+
+from browser_cli.automation.persistence.store import AutomationStore
+
+__all__ = ["AutomationStore"]