browser-agent-python-sdk 0.1.0__py3-none-macosx_15_0_arm64.whl

browser_agent/__init__.py

@@ -0,0 +1,18 @@
+from .errors import BrowserAgentError, BrowserAgentErrorCode
+from .events import (
+    BrowserAgentEvent, ErrorEvent, RunCompletedEvent, RunStartedEvent,
+    TaskResultEvent, UserTakeoverEvent,
+)
+from .models import (
+    BrowserAgentCredential, BrowserAgentLogEntry, BrowserAgentResult, BrowserAgentTask,
+    BrowserAgentTaskResult, BrowserAgentTaskRunResult, BrowserAgentValidatorResult,
+    Provider, ReasoningEffort, UserTakeoverCategory,
+)
+from .run import BrowserAgent, BrowserAgentRun
+
+__all__ = """
+BrowserAgent BrowserAgentCredential BrowserAgentError BrowserAgentErrorCode BrowserAgentEvent BrowserAgentLogEntry
+BrowserAgentResult BrowserAgentRun BrowserAgentTask BrowserAgentTaskResult
+BrowserAgentTaskRunResult BrowserAgentValidatorResult ErrorEvent Provider ReasoningEffort
+RunCompletedEvent RunStartedEvent TaskResultEvent UserTakeoverCategory UserTakeoverEvent
+""".split()

browser_agent/errors.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+from typing import Literal
+
+BrowserAgentErrorCode = Literal[
+    "CLI_NOT_FOUND", "CLI_VERSION_INCOMPATIBLE", "CHROME_NOT_FOUND", "CONFIG_INVALID",
+    "PROCESS_START_FAILED", "PROCESS_EXITED", "PROTOCOL_ERROR", "CANCELLED",
+]
+@dataclass(frozen=True, slots=True)
+class BrowserAgentError(Exception):
+    code: BrowserAgentErrorCode
+    message: str
+    details: dict[str, object] | None = None
+    cause: object | None = None
+
+    def __post_init__(self) -> None:
+        Exception.__init__(self, self.message)
+def redact(value: str, secrets: list[str], paths: list[str]) -> str:
+    result = value
+    for secret in secrets:
+        if secret:
+            result = result.replace(secret, "<redacted>")
+    for internal_path in paths:
+        if internal_path:
+            result = result.replace(internal_path, "<internal>")
+    return result
+def normalize_error(
+    error: BaseException, code: BrowserAgentErrorCode,
+    secrets: list[str], paths: list[str],
+) -> BrowserAgentError:
+    if isinstance(error, BrowserAgentError):
+        return error
+    message = redact(str(error), secrets, paths)
+    return BrowserAgentError(code, message, cause=RuntimeError(message))

browser_agent/events.py

@@ -0,0 +1,73 @@
+import asyncio
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Generic, Literal, TypeAlias, TypeVar
+
+from .errors import BrowserAgentError
+from .models import BrowserAgentResult, BrowserAgentTaskResult, UserTakeoverCategory
+@dataclass(frozen=True, slots=True)
+class RunStartedEvent:
+    run_id: str
+    type: Literal["run_started"] = "run_started"
+@dataclass(frozen=True, slots=True)
+class UserTakeoverEvent:
+    run_id: str
+    task_id: str
+    reason: str
+    category: UserTakeoverCategory
+    type: Literal["user_takeover"] = "user_takeover"
+@dataclass(frozen=True, slots=True)
+class TaskResultEvent:
+    run_id: str
+    result: BrowserAgentTaskResult
+    type: Literal["task_result"] = "task_result"
+@dataclass(frozen=True, slots=True)
+class RunCompletedEvent:
+    run_id: str
+    result: BrowserAgentResult
+    type: Literal["run_completed"] = "run_completed"
+@dataclass(frozen=True, slots=True)
+class ErrorEvent:
+    run_id: str
+    error: BrowserAgentError
+    type: Literal["error"] = "error"
+BrowserAgentEvent: TypeAlias = (
+    RunStartedEvent
+    | UserTakeoverEvent
+    | TaskResultEvent
+    | RunCompletedEvent
+    | ErrorEvent
+)
+T = TypeVar("T")
+class ReplayEvents(Generic[T]):
+    def __init__(self) -> None:
+        self._items: list[T] = []
+        self._waiters: set[asyncio.Future[None]] = set()
+        self._closed = False
+    def publish(self, item: T) -> None:
+        if self._closed:
+            return
+        self._items.append(item)
+        self._wake()
+    def close(self) -> None:
+        self._closed = True
+        self._wake()
+    async def iterate(self) -> AsyncIterator[T]:
+        index = 0
+        while True:
+            while index < len(self._items):
+                yield self._items[index]
+                index += 1
+            if self._closed:
+                return
+            waiter = asyncio.get_running_loop().create_future()
+            self._waiters.add(waiter)
+            try:
+                await waiter
+            finally:
+                self._waiters.discard(waiter)
+    def _wake(self) -> None:
+        for waiter in self._waiters:
+            if not waiter.done():
+                waiter.set_result(None)
+        self._waiters.clear()

browser_agent/models.py

@@ -0,0 +1,52 @@
+from dataclasses import dataclass
+from collections.abc import Sequence
+from datetime import datetime
+from typing import Literal, TypeAlias
+
+Provider: TypeAlias = Literal["openai", "vllm", "together", "anthropic", "google"]
+ReasoningEffort: TypeAlias = Literal[
+    "none", "minimal", "low", "medium", "high", "max", "enabled"
+]
+UserTakeoverCategory: TypeAlias = Literal[
+    "authentication", "otp", "verification", "payment", "other"
+]
+@dataclass(frozen=True, slots=True)
+class BrowserAgentCredential:
+    username: str
+    password: str
+    domain: str
+@dataclass(frozen=True, slots=True)
+class BrowserAgentTask:
+    task: str
+    url: str | None = None
+    credentials: Sequence[BrowserAgentCredential] = ()
+@dataclass(frozen=True, slots=True)
+class BrowserAgentLogEntry:
+    run_id: str
+    message: str
+    timestamp: datetime
+    source: Literal["stderr"] = "stderr"
+@dataclass(frozen=True, slots=True)
+class BrowserAgentValidatorResult:
+    ran: bool
+    success: bool
+    summary: str
+@dataclass(frozen=True, slots=True)
+class BrowserAgentTaskRunResult:
+    run_index: int
+    completed: bool
+    data: object
+    validator: BrowserAgentValidatorResult
+@dataclass(frozen=True, slots=True)
+class BrowserAgentTaskResult:
+    task_id: str
+    status: Literal["completed", "failed"]
+    runs: tuple[BrowserAgentTaskRunResult, ...]
+    errors: tuple[str, ...]
+@dataclass(frozen=True, slots=True)
+class BrowserAgentResult:
+    run_id: str
+    status: Literal["completed", "failed", "cancelled"]
+    tasks: tuple[BrowserAgentTaskResult, ...]
+    started_at: datetime
+    finished_at: datetime

browser_agent/options.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+from .errors import BrowserAgentError
+from .models import (
+    BrowserAgentCredential, BrowserAgentLogEntry, BrowserAgentTask, Provider,
+    ReasoningEffort,
+)
+
+PROVIDER_ENV: dict[Provider, str] = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "google": "GOOGLE_API_KEY",
+    "together": "TOGETHER_API_KEY",
+    "vllm": "VLLM_API_KEY",
+}
+OPENAI = (
+    "gpt-5.4", "gpt-5.4-mini", "gpt-5.5",
+    "gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol",
+)
+CAPABILITIES = [
+    *(("openai", model, False, ("none", "minimal", "low", "medium", "high"), "low")
+      for model in OPENAI),
+    ("together", "zai-org/GLM-5.2", False, ("none", "high", "max"), "high"),
+    ("vllm", "qwen", True, ("none", "enabled"), "enabled"),
+    ("vllm", "glm", True, ("none",), "none"),
+]
+@dataclass(frozen=True, slots=True)
+class ResolvedOptions:
+    provider: Provider
+    model: str
+    reasoning_effort: ReasoningEffort
+    api_key: str | None
+    api_key_environment: str
+    endpoint_url: str | None
+    headless: bool
+    executable_path: str | None
+    download_directory: str
+    workspace_directory: str | None
+    user_takeover_tool: bool
+    max_steps: int
+    concurrency: int
+    runs_per_task: int
+    retry_count: int
+    on_log: Callable[[BrowserAgentLogEntry], None] | None
+def invalid(message: str):
+    raise BrowserAgentError("CONFIG_INVALID", message)
+def positive(value: int, default: int) -> int:
+    value = default if value is None else value
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        invalid("Execution limits must be positive integers.")
+    return value
+def reasoning(provider: Provider, model: str, effort: ReasoningEffort | None):
+    capability = next(
+        (item for item in CAPABILITIES if item[0] == provider and
+         (item[1].lower() in model.lower() if item[2] else item[1] == model)),
+        None,
+    )
+    if capability is None and provider in ("openai", "together", "vllm"):
+        invalid(f"Unknown model '{model}' for '{provider}'.")
+    resolved = effort or (capability[4] if capability else None)
+    if resolved is None:
+        invalid("reasoning_effort is required for this model.")
+    if capability and resolved not in capability[3]:
+        invalid(f"Unsupported reasoning_effort '{resolved}' for this model.")
+    return resolved
+def resolve_options(**values) -> ResolvedOptions:
+    provider, model = values["provider"], values["model"]
+    downloads = values["download_directory"]
+    if provider not in PROVIDER_ENV:
+        invalid(f"Unsupported provider '{provider}'.")
+    if not isinstance(model, str) or not model.strip():
+        invalid("model must be a non-empty string.")
+    if not isinstance(downloads, str) or not downloads.strip():
+        invalid("download_directory must be a non-empty string.")
+    endpoint = values["endpoint_url"]
+    if endpoint:
+        parsed = urlparse(endpoint)
+        if parsed.scheme not in ("http", "https") or not parsed.netloc:
+            invalid("endpoint_url must be an absolute HTTP(S) URL.")
+    if provider == "vllm" and not endpoint:
+        invalid("endpoint_url is required for vllm.")
+    environment = PROVIDER_ENV[provider]
+    api_key = (values["api_key"] or "").strip() or os.environ.get(environment)
+    if provider != "vllm" and not api_key:
+        invalid(f"Missing API key for provider '{provider}'.")
+    retry = values["retry_count"]
+    if isinstance(retry, bool) or not isinstance(retry, int) or retry < 0:
+        invalid("retry_count must be an integer greater than or equal to zero.")
+    absolute = lambda value: str(Path(value).resolve()) if value else None
+    return ResolvedOptions(
+        provider, model.strip(), reasoning(provider, model.strip(), values["reasoning_effort"]),
+        api_key, environment, endpoint, values["headless"], absolute(values["executable_path"]),
+        absolute(downloads) or "", absolute(values["workspace_directory"]),
+        values["user_takeover_tool"], positive(values["max_steps"], 50),
+        positive(values["concurrency"], 4), positive(values["runs_per_task"], 1),
+        retry, values["on_log"],
+    )
+def normalize_tasks(value: BrowserAgentTask | Sequence[BrowserAgentTask]):
+    tasks = [value] if isinstance(value, BrowserAgentTask) else list(value)
+    if not tasks:
+        invalid("At least one task is required.")
+    for item in tasks:
+        if not isinstance(item, BrowserAgentTask) or not item.task.strip():
+            invalid("Each task must contain a non-empty task string.")
+        if item.url is not None and not item.url.strip():
+            invalid("Task URLs must be non-empty strings.")
+        if not isinstance(item.credentials, Sequence) or isinstance(item.credentials, str):
+            invalid("Task credentials must be a sequence.")
+        for credential in item.credentials:
+            if not isinstance(credential, BrowserAgentCredential):
+                invalid("Each credential must be a BrowserAgentCredential.")
+            if not credential.username.strip():
+                invalid("Credential usernames must be non-empty strings.")
+            if not credential.password:
+                invalid("Credential passwords must be non-empty strings.")
+            if not credential.domain.strip():
+                invalid("Credential domains must be non-empty strings.")
+    return [
+        BrowserAgentTask(
+            item.task.strip(), item.url.strip() if item.url else None,
+            tuple(BrowserAgentCredential(
+                credential.username.strip(), credential.password, credential.domain.strip()
+            ) for credential in item.credentials),
+        )
+        for item in tasks
+    ]
+def child_environment(options: ResolvedOptions) -> dict[str, str]:
+    environment = {key: value for key, value in os.environ.items()
+                   if key not in PROVIDER_ENV.values()}
+    if options.api_key:
+        environment[options.api_key_environment] = options.api_key
+    return environment

browser_agent/protocol.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from .errors import BrowserAgentError, redact
+from .models import BrowserAgentLogEntry, BrowserAgentTask
+
+@dataclass(slots=True)
+class AgentProcess:
+    process: asyncio.subprocess.Process
+
+    async def messages(self) -> AsyncIterator[dict[str, object]]:
+        assert self.process.stdout
+        while line := await self.process.stdout.readline():
+            if not line.strip():
+                continue
+            try:
+                value = json.loads(line)
+            except json.JSONDecodeError as error:
+                raise BrowserAgentError(
+                    "PROTOCOL_ERROR", "CLI emitted malformed JSON-RPC."
+                ) from error
+            if not isinstance(value, dict) or value.get("jsonrpc") != "2.0":
+                raise BrowserAgentError(
+                    "PROTOCOL_ERROR", "CLI emitted an invalid JSON-RPC message."
+                )
+            yield value
+    async def logs(self) -> AsyncIterator[str]:
+        assert self.process.stderr
+        while line := await self.process.stderr.readline():
+            yield line.decode(errors="replace").rstrip("\r\n")
+async def start_agent_process(
+    executable: str, config_path: str, environment: dict[str, str]
+) -> AgentProcess:
+    try:
+        process = await asyncio.create_subprocess_exec(
+            executable,
+            config_path,
+            "--rpc",
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=environment,
+        )
+    except OSError as error:
+        raise BrowserAgentError(
+            "PROCESS_START_FAILED", "browser-agent process could not be started."
+        ) from error
+    return AgentProcess(process)
+async def request_run(
+    agent: AgentProcess, tasks: list[BrowserAgentTask] | tuple[BrowserAgentTask, ...] = ()
+) -> None:
+    assert agent.process.stdin
+    rpc_tasks = [
+        {"credentials": [
+            {"username": value.username, "password": value.password, "domain": value.domain}
+            for value in task.credentials
+        ]} if task.credentials else {}
+        for task in tasks
+    ]
+    agent.process.stdin.write(
+        (
+            json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "id": 1,
+                    "method": "crafty/run",
+                    "params": {"tasks": rpc_tasks} if any(task for task in rpc_tasks) else {},
+                }
+            )
+            + "\n"
+        ).encode()
+    )
+    await agent.process.stdin.drain()
+async def terminate_process(agent: AgentProcess, grace: float = 5.0) -> None:
+    if agent.process.returncode is not None:
+        return
+    agent.process.terminate()
+    try:
+        await asyncio.wait_for(agent.process.wait(), timeout=grace)
+    except TimeoutError:
+        agent.process.kill()
+        await agent.process.wait()
+async def consume_logs(
+    process: AgentProcess,
+    run_id: str,
+    callback,
+    secrets: list[str],
+    paths: list[str],
+) -> None:
+    async for line in process.logs():
+        try:
+            if callback:
+                callback(BrowserAgentLogEntry(
+                    run_id, redact(line, secrets, paths), datetime.now(timezone.utc)
+                ))
+        except BaseException:
+            pass

browser_agent/rpc.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .errors import BrowserAgentError, redact
+from .events import RunStartedEvent, TaskResultEvent, UserTakeoverEvent
+from .models import (
+    BrowserAgentTaskResult,
+    BrowserAgentTaskRunResult,
+    BrowserAgentValidatorResult,
+)
+
+def record(value):
+    if not isinstance(value, dict):
+        raise BrowserAgentError(
+            "PROTOCOL_ERROR", "CLI emitted invalid task-result parameters."
+        )
+    return value
+def normalize_result(value) -> BrowserAgentTaskResult:
+    source = record(value)
+    task_id, status, raw_runs = (
+        source.get("task_id"), source.get("status"), source.get("runs")
+    )
+    if not isinstance(task_id, str) or status not in ("completed", "failed") \
+            or not isinstance(raw_runs, list):
+        raise BrowserAgentError(
+            "PROTOCOL_ERROR", "CLI emitted invalid task-result parameters."
+        )
+    runs = []
+    for value in raw_runs:
+        run = record(value)
+        validator = record(run.get("validator"))
+        if not isinstance(run.get("run_index"), int) \
+                or not isinstance(run.get("completed"), bool) \
+                or not isinstance(validator.get("ran"), bool) \
+                or not isinstance(validator.get("success"), bool) \
+                or not isinstance(validator.get("summary"), str):
+            raise BrowserAgentError(
+                "PROTOCOL_ERROR", "CLI emitted an invalid task run."
+            )
+        runs.append(BrowserAgentTaskRunResult(
+            run["run_index"], run["completed"], run.get("data"),
+            BrowserAgentValidatorResult(
+                validator["ran"], validator["success"], validator["summary"]
+            ),
+        ))
+    errors = source.get("errors")
+    return BrowserAgentTaskResult(
+        task_id, status, tuple(runs),
+        tuple(item for item in errors if isinstance(item, str))
+        if isinstance(errors, list) else (),
+    )
+def order(task_id: str) -> int:
+    prefix, separator, suffix = task_id.partition("-")
+    return int(suffix) if prefix == "task" and separator and suffix.isdigit() else 2**31
+class RpcState:
+    def __init__(self, run_id: str, secrets: list[str], paths: list[str]) -> None:
+        self.run_id, self.secrets, self.paths = run_id, secrets, paths
+        self._results: dict[str, BrowserAgentTaskResult] = {}
+    @property
+    def results(self) -> tuple[BrowserAgentTaskResult, ...]:
+        return tuple(sorted(self._results.values(), key=lambda item: order(item.task_id)))
+    def handle(self, message: dict[str, object]):
+        if message.get("id") == 1:
+            return self._accept(message)
+        method = message.get("method")
+        params = message.get("params")
+        source = params if isinstance(params, dict) else {}
+        if method == "crafty/status":
+            category = source.get("category")
+            if category not in ("authentication", "otp", "verification", "payment"):
+                category = "other"
+            return UserTakeoverEvent(
+                self.run_id, str(source.get("task_id", "")),
+                str(source.get("reason", "")), category
+            )
+        if method == "crafty/task_result":
+            result = normalize_result(params)
+            result = replace(result, errors=tuple(
+                redact(error, self.secrets, self.paths) for error in result.errors
+            ))
+            self._results[result.task_id] = result
+            return TaskResultEvent(self.run_id, result)
+        if method == "crafty/all_tasks_completed":
+            return "complete"
+        if method == "crafty/error":
+            raise BrowserAgentError(
+                "PROCESS_EXITED",
+                redact(str(source.get("message", "browser-agent failed.")),
+                       self.secrets, self.paths),
+            )
+    def _accept(self, message: dict[str, object]):
+        error = message.get("error")
+        if isinstance(error, dict):
+            data = error.get("data")
+            code = data.get("code") if isinstance(data, dict) else None
+            code = code if code in ("CONFIG_INVALID", "CHROME_NOT_FOUND") else "PROTOCOL_ERROR"
+            raise BrowserAgentError(
+                code,
+                redact(str(error.get("message", "CLI rejected the run.")),
+                       self.secrets, self.paths),
+            )
+        result = message.get("result")
+        if not isinstance(result, dict) or result.get("accepted") is not True:
+            raise BrowserAgentError("PROTOCOL_ERROR", "CLI did not accept the run.")
+        return RunStartedEvent(self.run_id)

browser_agent/run.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import AsyncIterator, Callable, Sequence
+from contextlib import suppress
+from datetime import datetime, timezone
+
+from .errors import BrowserAgentError, normalize_error
+from .events import BrowserAgentEvent, ErrorEvent, ReplayEvents, RunCompletedEvent
+from .models import (
+    BrowserAgentLogEntry,
+    BrowserAgentResult,
+    BrowserAgentTask,
+    Provider,
+    ReasoningEffort,
+)
+from .options import ResolvedOptions, child_environment, normalize_tasks, resolve_options
+from .protocol import AgentProcess, consume_logs, request_run, start_agent_process, terminate_process
+from .rpc import RpcState
+from .runtime import (
+    DEFAULT_EXECUTABLE_DEPENDENCIES,
+    ExecutableDependencies,
+    RuntimeFiles,
+    create_runtime_files,
+)
+
+
+class BrowserAgent:
+    def __init__(
+        self, *, provider: Provider, model: str, download_directory: str,
+        reasoning_effort: ReasoningEffort | None = None, api_key: str | None = None,
+        endpoint_url: str | None = None, headless: bool = False,
+        executable_path: str | None = None, workspace_directory: str | None = None,
+        user_takeover_tool: bool = True, max_steps: int = 50, concurrency: int = 4,
+        runs_per_task: int = 1, retry_count: int = 2,
+        on_log: Callable[[BrowserAgentLogEntry], None] | None = None,
+    ) -> None:
+        self._options = resolve_options(**locals())
+        self._dependencies: ExecutableDependencies = DEFAULT_EXECUTABLE_DEPENDENCIES
+        self._executable: asyncio.Future[str] | None = None
+
+    def run(
+        self, value: BrowserAgentTask | Sequence[BrowserAgentTask], *,
+        on_event: Callable[[BrowserAgentEvent], None] | None = None,
+    ) -> BrowserAgentRun:
+        tasks = normalize_tasks(value)
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError as error:
+            raise BrowserAgentError(
+                "PROCESS_START_FAILED",
+                "run() must be called inside an active asyncio event loop.",
+            ) from error
+        if self._executable is None:
+            self._executable = asyncio.create_task(self._verify())
+        return BrowserAgentRun(
+            str(uuid.uuid4()), self._options, tasks, self._executable, on_event
+        )
+
+    async def _verify(self) -> str:
+        executable = await self._dependencies.resolve()
+        await self._dependencies.verify(executable)
+        return executable
+
+
+class BrowserAgentRun:
+    def __init__(
+        self, run_id: str, options: ResolvedOptions, tasks: list[BrowserAgentTask],
+        executable: asyncio.Future[str],
+        on_event: Callable[[BrowserAgentEvent], None] | None,
+    ) -> None:
+        self.id, self._options, self._tasks = run_id, options, tasks
+        self._on_event = on_event
+        self._stream = ReplayEvents[BrowserAgentEvent]()
+        self._process: AgentProcess | None = None
+        self._terminal: asyncio.Future[str] | None = None
+        self._cancel_requested = False
+        self._rpc: RpcState | None = None
+        self.result = asyncio.create_task(self._execute(executable))
+
+    def events(self) -> AsyncIterator[BrowserAgentEvent]:
+        return self._stream.iterate()
+
+    async def cancel(self) -> None:
+        self._cancel_requested = True
+        self._settle("cancelled")
+        if self._process:
+            await terminate_process(self._process)
+        with suppress(BaseException):
+            await self.result
+
+    def _publish(self, event: BrowserAgentEvent) -> None:
+        self._stream.publish(event)
+        try:
+            if self._on_event:
+                self._on_event(event)
+        except BaseException:
+            pass
+
+    def _complete(self, status: str, started: datetime) -> BrowserAgentResult:
+        result = BrowserAgentResult(
+            self.id, status, self._rpc.results if self._rpc else (),
+            started, datetime.now(timezone.utc),
+        )
+        self._publish(RunCompletedEvent(self.id, result))
+        self._stream.close()
+        return result
+
+    def _settle(self, value: str | BaseException) -> None:
+        if not self._terminal or self._terminal.done():
+            return
+        if isinstance(value, BaseException):
+            self._terminal.set_exception(value)
+        else:
+            self._terminal.set_result(value)
+
+    async def _pump(self, process: AgentProcess) -> None:
+        try:
+            async for message in process.messages():
+                event = self._rpc.handle(message)
+                if event == "complete":
+                    self._settle("completed")
+                elif event:
+                    self._publish(event)
+        except BaseException as error:
+            self._settle(error)
+
+    async def _watch_exit(self, process: AgentProcess) -> None:
+        await process.process.wait()
+        self._settle(
+            "cancelled" if self._cancel_requested else
+            BrowserAgentError("PROCESS_EXITED", "browser-agent exited early.")
+        )
+
+    async def _execute(self, executable: asyncio.Future[str]) -> BrowserAgentResult:
+        started, files = datetime.now(timezone.utc), None
+        secrets = ([self._options.api_key] if self._options.api_key else []) + [
+            value
+            for task in self._tasks
+            for credential in task.credentials
+            for value in (credential.username, credential.password, credential.domain)
+        ]
+        try:
+            binary = await executable
+            if self._cancel_requested:
+                return self._complete("cancelled", started)
+            files = create_runtime_files(self._options, self._tasks)
+            self._process = await start_agent_process(
+                binary, files.config_path, child_environment(self._options)
+            )
+            self._rpc = RpcState(self.id, secrets, files.internal_paths)
+            logs = asyncio.create_task(consume_logs(
+                self._process, self.id, self._options.on_log, secrets, files.internal_paths
+            ))
+            self._terminal = asyncio.get_running_loop().create_future()
+            asyncio.create_task(self._pump(self._process))
+            asyncio.create_task(self._watch_exit(self._process))
+            await request_run(self._process, self._tasks)
+            outcome = await self._terminal
+            if outcome == "cancelled":
+                await terminate_process(self._process)
+            else:
+                if await self._process.process.wait() != 0:
+                    raise BrowserAgentError(
+                        "PROCESS_EXITED", "browser-agent exited unsuccessfully."
+                    )
+                if len(self._rpc.results) != len(self._tasks):
+                    raise BrowserAgentError(
+                        "PROTOCOL_ERROR", "browser-agent completed without all task results."
+                    )
+            await logs
+            files.cleanup()
+            files = None
+            status = "cancelled" if outcome == "cancelled" else (
+                "failed" if any(item.status == "failed" for item in self._rpc.results)
+                else "completed"
+            )
+            return self._complete(status, started)
+        except BaseException as error:
+            if self._process:
+                await terminate_process(self._process)
+            if files:
+                files.cleanup()
+            normalized = normalize_error(
+                error, "PROCESS_EXITED", secrets, files.internal_paths if files else []
+            )
+            self._publish(ErrorEvent(self.id, normalized))
+            self._stream.close()
+            raise normalized
+        finally:
+            self._terminal = None

browser_agent/runtime.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import platform
+import shutil
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from .errors import BrowserAgentError
+from .models import BrowserAgentTask
+from .options import ResolvedOptions
+
+def platform_key(system: str | None = None, machine: str | None = None) -> str:
+    system = system or sys.platform
+    machine = (machine or platform.machine()).lower()
+    architecture = {"aarch64": "arm64", "amd64": "x64", "x86_64": "x64"}.get(machine, machine)
+    return f"{system}-{architecture}"
+def bundled_executable(system: str | None = None, machine: str | None = None) -> Path:
+    system = system or sys.platform
+    suffix = ".exe" if system == "win32" else ""
+    return Path(__file__).parent / "bin" / platform_key(system, machine) / f"browser-agent{suffix}"
+async def resolve_executable(executable: Path | None = None) -> str:
+    executable = executable or bundled_executable()
+    if not executable.is_file() or not os.access(executable, os.X_OK):
+        raise BrowserAgentError(
+            "CLI_NOT_FOUND",
+            f"Bundled browser-agent executable is unavailable for {platform_key()}.",
+        )
+    return str(executable)
+async def verify_executable(executable: str, timeout: float = 5) -> None:
+    try:
+        process = await asyncio.create_subprocess_exec(
+            executable, "--version-json",
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await asyncio.wait_for(process.communicate(), timeout)
+    except TimeoutError as error:
+        process.kill()
+        await process.wait()
+        raise BrowserAgentError(
+            "CLI_VERSION_INCOMPATIBLE", "Bundled browser-agent version check timed out."
+        ) from error
+    except OSError as error:
+        raise BrowserAgentError(
+            "CLI_NOT_FOUND", "Bundled browser-agent executable could not be started."
+        ) from error
+    try:
+        if process.returncode or json.loads(stdout)["rpcProtocolVersion"] != 1:
+            raise ValueError
+    except (ValueError, KeyError, json.JSONDecodeError) as error:
+        raise BrowserAgentError(
+            "CLI_VERSION_INCOMPATIBLE",
+            "Bundled browser-agent uses an incompatible RPC protocol.",
+        ) from error
+@dataclass(frozen=True, slots=True)
+class ExecutableDependencies:
+    resolve: Callable[[], Awaitable[str]]
+    verify: Callable[[str], Awaitable[None]]
+DEFAULT_EXECUTABLE_DEPENDENCIES = ExecutableDependencies(
+    resolve_executable, verify_executable
+)
+@dataclass(slots=True)
+class RuntimeFiles:
+    config_path: str
+    internal_paths: list[str]
+    def cleanup(self) -> None:
+        for owned in self.internal_paths:
+            shutil.rmtree(owned, ignore_errors=True)
+def create_runtime_files(options: ResolvedOptions, tasks: list[BrowserAgentTask]):
+    owned: list[str] = []
+    try:
+        runtime = tempfile.mkdtemp(prefix="browser-agent-sdk-")
+        owned.append(runtime)
+        os.chmod(runtime, 0o700)
+        workspace = options.workspace_directory
+        if workspace is None:
+            workspace = tempfile.mkdtemp(prefix=".browser-agent-workspace-", dir=os.getcwd())
+            owned.append(workspace)
+        Path(options.download_directory).mkdir(parents=True, exist_ok=True)
+        Path(workspace).mkdir(parents=True, exist_ok=True)
+        config_path = str(Path(runtime) / "config.yaml")
+        config = {
+            "provider": options.provider, "model": options.model,
+            "reasoning_effort": options.reasoning_effort,
+            **({"endpoint_url": options.endpoint_url} if options.endpoint_url else {}),
+            "feature_flags": {"user_takeover_tool": options.user_takeover_tool},
+            "headless": options.headless,
+            **({"executable_path": options.executable_path} if options.executable_path else {}),
+            "download_dir": options.download_directory, "file_workspace_root": workspace,
+            "max_steps": options.max_steps, "concurrency": options.concurrency,
+            "task_runs": options.runs_per_task, "task_run_retry_count": options.retry_count,
+            "validator_lifecycle": {"mode": "terminal", "max_failures": 3},
+            "wait_between_tasks_ms": 0, "save_steps_context": True, "save_task_logs": False,
+            "step_messages_jsonl_path": str(Path(runtime) / "steps.jsonl"),
+            "tasks": [{"task": task.task, **({"url": task.url} if task.url else {})}
+                      for task in tasks],
+        }
+        descriptor = os.open(config_path, os.O_WRONLY | os.O_CREAT, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as output:
+            json.dump(config, output)
+        return RuntimeFiles(config_path, owned)
+    except BaseException:
+        for path in owned:
+            shutil.rmtree(path, ignore_errors=True)
+        raise

browser_agent_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: browser-agent-python-sdk
+Version: 0.1.0
+Summary: Python SDK for the Crafty Browser Agent
+Project-URL: Homepage, https://getcrafty.io
+Project-URL: Repository, https://github.com/pb05/operator
+Project-URL: Issues, https://github.com/pb05/operator/issues
+Author: Crafty
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: ai,automation,browser,browser-agent,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: coverage[toml]<8,>=7.6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Browser Agent Python SDK
+
+Dependency-free async Python wrapper for the bundled `browser-agent`
+executable. Requires Python 3.11 or newer.
+
+```sh
+pip install browser-agent-python-sdk
+```
+
+```python
+import os
+
+from browser_agent import BrowserAgent, BrowserAgentCredential, BrowserAgentTask
+
+agent = BrowserAgent(
+    provider="openai",
+    model="gpt-5.4",
+    download_directory="./downloads",
+)
+
+run = agent.run(
+    BrowserAgentTask(
+        "Open my account",
+        "https://example.com",
+        credentials=(
+            BrowserAgentCredential(
+                username="person@example.com",
+                password=os.environ["EXAMPLE_PASSWORD"],
+                domain="https://example.com",
+            ),
+        ),
+    )
+)
+async for event in run.events():
+    print(event)
+result = await run.result
+```
+
+Call `run()` inside an active asyncio loop. API keys may be passed as `api_key`
+or inherited from the matching provider environment variable. They are passed
+only to the child process.
+
+Task credentials are sent only over the child process's local stdin stream,
+encrypted immediately by the CLI, excluded from generated configuration, and
+redacted from SDK logs and errors.
+
+Development:
+
+```sh
+uv run --extra test coverage run -m unittest discover -s tests
+uv run --extra test coverage report
+uv build --wheel
+```
+
+Coverage fails below 100% statements or branches.

browser_agent_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+browser_agent/__init__.py,sha256=8O7WmsPpL9Drg9UK_BKJ-41xQA6nFP08P-21mZPhyxg,888
+browser_agent/errors.py,sha256=ZoXXGRfFpA_KBbbyIAXODoC1T5jmvEZIp-lKhfwDuxg,1207
+browser_agent/events.py,sha256=IUsIajBe4uhH3A8ckEDT63UpLhGUhQNEknctXJ8YV20,2244
+browser_agent/models.py,sha256=U_t6gJi0cbvF68izYR5JEXC9Bh--yhx8U4RtJ_P8w6g,1594
+browser_agent/options.py,sha256=MUbn2JXxYWC6ueuTTuspCWXUPRKhcKWH4fRFG7RrvVg,6161
+browser_agent/protocol.py,sha256=4lkGGSxWGSm_3vEmSVPL2Sez3zHL1Kdl4IT33ngK5Rw,3462
+browser_agent/rpc.py,sha256=5cr_r6xnzNjNGis43MAqREc8QlWF3RqJwvW5CzvUWhc,4626
+browser_agent/run.py,sha256=iLzO8gjHH4nSaxT_vqto065Y2BqPhVdirFu-OLMTPZg,7702
+browser_agent/runtime.py,sha256=1FDwO2bmSv1CRAxuzIvnlPtixie7mzzOGANSKfArcmM,4949
+browser_agent_python_sdk-0.1.0.dist-info/METADATA,sha256=2QJ9E0R2NVze-6LtbcFTEyOQP4VtW6Fycr9pKQlpIMo,2438
+browser_agent_python_sdk-0.1.0.dist-info/WHEEL,sha256=NIjYS0v0Um9i20VOZcStv8f2DIdr7FbyXbarsfXbfSk,102
+browser_agent_python_sdk-0.1.0.dist-info/licenses/LICENSE.md,sha256=VVWZ9N-YU8mvzb1nJBnK4WKbHwijl5PSPz0F7XozB7o,1071
+browser_agent_python_sdk-0.1.0.dist-info/RECORD,,

browser_agent_python_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: false
+Tag: py3-none-macosx_15_0_arm64

browser_agent_python_sdk-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crafty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.