r2flow-engine 0.8.11__py3-none-any.whl

r2flow/__init__.py

@@ -0,0 +1,116 @@
+"""R2Flow — Free Python RPA engine for creating automation bots."""
+
+from r2flow.core.config import Config, load_config
+from r2flow.core.errors import (
+    BusinessError,
+    Cancelled,
+    ConfigError,
+    ElementNotFound,
+    InfrastructureError,
+    InvalidInput,
+    PlatformError,
+    ToolError,
+)
+from r2flow.core.http_queue import HttpQueue, HttpQueueError
+from r2flow.core.logging import JsonlEventLogger
+from r2flow.core.queue import (
+    ClaimedItem,
+    InMemoryQueue,
+    LeaseRenewable,
+    Queue,
+    QueueInfo,
+    QueueItem,
+    SqliteQueue,
+)
+from r2flow.core.retry import RetryTool
+from r2flow.core.schema import validate_against_schema
+from r2flow.core.selectors import SelectorStore
+from r2flow.core.tool import AbstractTool, Tool, tool
+from r2flow.core.transactions import (
+    ItemOutcome,
+    TransactionContextMiddleware,
+    TransactionReport,
+    current_transaction_id,
+    run_transactions,
+    run_transactions_async,
+)
+from r2flow.facade import (
+    ClickResult,
+    InputTextResult,
+    ProcessHandle,
+    SetTextResult,
+    R2Flow,
+)
+from r2flow.flow import FlowError, FlowRunner
+from r2flow.pack import (
+    PACK_MANIFEST,
+    TEMPLATE_FILE,
+    build_pack,
+    fetch_pack,
+    load_manifest,
+    load_template,
+    publish_pack,
+    validate_template,
+    verify_pack,
+    zip_pack,
+)
+
+try:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("r2flow-engine")
+except PackageNotFoundError:  # pragma: no cover — running from an uninstalled tree
+    __version__ = "0.8.11"
+
+__all__ = [
+    "AbstractTool",
+    "BusinessError",
+    "Cancelled",
+    "ClaimedItem",
+    "ClickResult",
+    "Config",
+    "ConfigError",
+    "ElementNotFound",
+    "FlowError",
+    "FlowRunner",
+    "HttpQueue",
+    "HttpQueueError",
+    "InMemoryQueue",
+    "InputTextResult",
+    "InvalidInput",
+    "ItemOutcome",
+    "JsonlEventLogger",
+    "LeaseRenewable",
+    "PACK_MANIFEST",
+    "PlatformError",
+    "ProcessHandle",
+    "Queue",
+    "QueueInfo",
+    "QueueItem",
+    "RetryTool",
+    "SelectorStore",
+    "SetTextResult",
+    "R2Flow",
+    "SqliteQueue",
+    "InfrastructureError",
+    "TEMPLATE_FILE",
+    "Tool",
+    "ToolError",
+    "TransactionContextMiddleware",
+    "TransactionReport",
+    "build_pack",
+    "current_transaction_id",
+    "fetch_pack",
+    "load_config",
+    "load_manifest",
+    "load_template",
+    "publish_pack",
+    "run_transactions",
+    "run_transactions_async",
+    "tool",
+    "validate_against_schema",
+    "validate_template",
+    "verify_pack",
+    "zip_pack",
+]

r2flow/core/__init__.py

@@ -0,0 +1,28 @@
+"""Core traits, types, and error definitions."""
+
+from r2flow.core.errors import (
+    BusinessError,
+    Cancelled,
+    ConfigError,
+    ElementNotFound,
+    InfrastructureError,
+    InvalidInput,
+    PlatformError,
+    ToolError,
+)
+from r2flow.core.registry import ToolRegistry
+from r2flow.core.tool import AbstractTool, Tool
+
+__all__ = [
+    "AbstractTool",
+    "BusinessError",
+    "Cancelled",
+    "ConfigError",
+    "ElementNotFound",
+    "InfrastructureError",
+    "InvalidInput",
+    "PlatformError",
+    "Tool",
+    "ToolError",
+    "ToolRegistry",
+]

r2flow/core/asset_tools.py

@@ -0,0 +1,84 @@
+"""Asset tools — fetch secrets at run time without storing them in the flow.
+
+The agent injects assets as environment variables (``R2FLOW_ASSET_*`` for a
+text asset, ``R2FLOW_ASSET_<NAME>_<FIELD>`` for credential fields); these
+tools read them back.
+
+Both tools set :attr:`AbstractTool.produces_secrets`, so the flow runner
+redacts the returned values from logs/errors and keeps the variables they
+land in out of the run-result snapshot sent back to the orchestrator.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from r2flow.core.assets import asset_provider_from_env
+from r2flow.core.errors import InvalidInput
+from r2flow.core.tool import AbstractTool
+
+
+def _asset_name(config: dict[str, Any]) -> str:
+    name = config.get("name")
+    if not isinstance(name, str) or not name.strip():
+        raise InvalidInput(
+            "Missing required parameter: name (asset name)",
+            param="name",
+            input_value=name,
+        )
+    return name.strip()
+
+
+class AssetGetTool(AbstractTool):
+    """Fetch a text asset (secret) by name."""
+
+    produces_secrets = True
+
+    @property
+    def name(self) -> str:
+        return "asset.get"
+
+    @property
+    def description(self) -> str:
+        return "Fetches a text asset (secret) from the agent environment by name"
+
+    def schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Asset name (e.g. crm-url) or a credential field (crm.login)",
+                },
+            },
+            "required": ["name"],
+        }
+
+    async def execute(self, config: dict[str, Any]) -> Any:
+        return asset_provider_from_env().get(_asset_name(config))
+
+
+class AssetCredentialTool(AbstractTool):
+    """Fetch a credential asset's fields (login / password / …)."""
+
+    produces_secrets = True
+
+    @property
+    def name(self) -> str:
+        return "asset.credential"
+
+    @property
+    def description(self) -> str:
+        return "Fetches a credential asset's fields (login, password, …) by name"
+
+    def schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Credential asset name (e.g. crm)"},
+            },
+            "required": ["name"],
+        }
+
+    async def execute(self, config: dict[str, Any]) -> Any:
+        return asset_provider_from_env().credential(_asset_name(config))

r2flow/core/assets.py

@@ -0,0 +1,258 @@
+"""Asset provider — runtime secrets for bots.
+
+Config files deliberately store only *references* to secrets (asset
+names, GUIDs) — never values. Values are fetched at runtime through an
+:class:`AssetProvider`, called from bot code (``bot.asset("db_password")``)
+instead of flowing through tool configs/results — so they can never
+leak into the JSONL audit log or flow files.
+
+The default provider reads environment variables (``R2FLOW_ASSET_*``);
+wire an orchestrator-backed implementation behind the same protocol.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Protocol, runtime_checkable
+
+from r2flow.core.errors import InvalidInput, PlatformError
+
+DEFAULT_ASSET_PREFIX = "R2FLOW_ASSET_"
+
+_MAX_ASSET_BYTES = 1_000_000
+
+
+def _check_no_redirect(response: Any, url: str) -> None:
+    """Fail when urlopen followed a redirect away from *url*."""
+    geturl = getattr(response, "geturl", None)
+    if callable(geturl):
+        try:
+            final = str(geturl())
+        except Exception:
+            return
+        if final and final != url:
+            raise PlatformError(f"asset fetch refused redirect to {final!r}", source=None)
+
+
+def _normalize(name: str) -> str:
+    return re.sub(r"[^A-Z0-9]+", "_", name.strip().upper())
+
+
+@runtime_checkable
+class AssetProvider(Protocol):
+    """Secret source contract."""
+
+    def get(self, name: str) -> str:
+        """Return the secret value for *name*; raise if unknown."""
+        ...
+
+    def credential(self, name: str) -> dict[str, str]:
+        """Return a credential's fields (or ``{"value": ...}`` for text)."""
+        ...
+
+
+class EnvAssetProvider:
+    """Asset provider over ``R2FLOW_ASSET_*`` environment variables.
+
+    ``bot.asset("db.password")`` reads ``R2FLOW_ASSET_DB_PASSWORD``:
+    the name is upper-cased and every non-alphanumeric run becomes a
+    single underscore.
+    """
+
+    def __init__(self, prefix: str = DEFAULT_ASSET_PREFIX) -> None:
+        if not isinstance(prefix, str) or not prefix:
+            raise InvalidInput(
+                "prefix must be a non-empty string", param="prefix", input_value=prefix
+            )
+        self._prefix = prefix
+        self._cache: dict[str, str] = {}
+
+    @property
+    def prefix(self) -> str:
+        """Env var prefix of this provider."""
+        return self._prefix
+
+    def get(self, name: str) -> str:
+        """Look up the env var for *name*.
+
+        Results are cached for the lifetime of the provider, so a bot
+        that fetches the same asset repeatedly pays the environment
+        lookup once.
+
+        Raises:
+            InvalidInput: If *name* is empty or the env var is not set.
+        """
+        if not isinstance(name, str) or not name.strip():
+            raise InvalidInput(
+                "asset name must be a non-empty string", param="name", input_value=name
+            )
+        key = self._prefix + re.sub(r"[^A-Z0-9]+", "_", name.strip().upper())
+        cached = self._cache.get(key)
+        if cached is not None:
+            return cached
+        value = os.environ.get(key)
+        if value is None:
+            raise InvalidInput(
+                f"Unknown asset {name!r}: environment variable {key!r} is not set",
+                param="name",
+                input_value=name,
+            )
+        self._cache[key] = value
+        return value
+
+    def credential(self, name: str) -> dict[str, str]:
+        """Credential fields for *name*, or ``{"value": ...}`` for text."""
+        fields = credential_fields(name, self._prefix)
+        if fields:
+            return fields
+        return {"value": self.get(name)}
+
+
+def credential_fields(name: str, prefix: str = DEFAULT_ASSET_PREFIX) -> dict[str, str]:
+    """All ``<prefix><NAME>_<FIELD>`` env vars for a credential *name*.
+
+    The agent injects a credential as one env var per field, e.g. asset
+    ``crm`` with ``login``/``password`` becomes ``R2FLOW_ASSET_CRM_LOGIN``
+    and ``R2FLOW_ASSET_CRM_PASSWORD``. Keys are returned lower-cased
+    (``{"login": ..., "password": ...}``); an empty result means either a
+    text asset or an unknown name.
+    """
+    base = prefix + _normalize(name)
+    marker = base + "_"
+    fields: dict[str, str] = {}
+    for key, value in os.environ.items():
+        if key.startswith(marker) and value != "":
+            field = key[len(marker) :].lower()
+            if field:
+                fields[field] = value
+    return fields
+
+
+class HttpAssetProvider:
+    """Fetch assets on demand from a r2flow-cloud orchestrator.
+
+    Resolves an asset by **id/GUID or name** (and ``name.field`` for a
+    credential field), so the engine no longer needs the whole vault
+    injected into the environment. Only used when the agent configures
+    ``R2FLOW_ORCHESTRATOR_URL`` + ``R2FLOW_AGENT_ID`` + a token; otherwise
+    :class:`EnvAssetProvider` is used.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        agent_id: str,
+        token: str,
+        process_id: str | None = None,
+        timeout: float = 15.0,
+        allow_insecure: bool = False,
+    ) -> None:
+        parsed = urllib.parse.urlparse(base_url)
+        if parsed.scheme not in ("http", "https"):
+            raise InvalidInput(
+                "orchestrator URL must be http(s)", param="base_url", input_value=base_url
+            )
+        host = parsed.hostname or ""
+        loopback = host in ("127.0.0.1", "::1", "localhost")
+        if parsed.scheme == "http" and not loopback and not allow_insecure:
+            raise InvalidInput(
+                "plain http to a non-loopback orchestrator is refused "
+                "(assets would travel in cleartext)",
+                param="base_url",
+                input_value=base_url,
+            )
+        self._base = base_url.rstrip("/")
+        self._agent_id = str(agent_id)
+        self._token = token
+        self._process_id = process_id
+        self._timeout = timeout
+        self._cache: dict[str, dict[str, Any]] = {}
+
+    def _fetch(self, ref: str) -> dict[str, Any] | None:
+        """One asset by id or name; ``None`` on 404 (so ``name.field`` can split)."""
+        if ref in self._cache:
+            return self._cache[ref]
+        url = (
+            f"{self._base}/api/agents/{urllib.parse.quote(self._agent_id, safe='')}"
+            f"/assets/{urllib.parse.quote(ref, safe='')}"
+        )
+        if self._process_id:
+            url += f"?process_id={urllib.parse.quote(self._process_id, safe='')}"
+        request = urllib.request.Request(url)
+        # Unredirected: never replayed to a redirect target.
+        request.add_unredirected_header("Authorization", f"Bearer {self._token}")
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                _check_no_redirect(response, url)
+                try:
+                    raw = response.read(_MAX_ASSET_BYTES + 1)
+                except TypeError:
+                    raw = response.read()
+                if isinstance(raw, str):
+                    raw = raw.encode("utf-8")
+                if len(raw) > _MAX_ASSET_BYTES:
+                    raise PlatformError("asset response too large", source=None)
+                data: Any = json.loads(bytes(raw).decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            exc.close()
+            if exc.code == 404:
+                return None
+            raise PlatformError(f"asset fetch failed with HTTP {exc.code}", source=exc) from exc
+        except (urllib.error.URLError, OSError, ValueError) as exc:
+            raise PlatformError(f"asset fetch failed: {exc}", source=exc) from exc
+        if isinstance(data, dict):
+            self._cache[ref] = data
+            return data
+        return None
+
+    def get(self, name: str) -> str:
+        data = self._fetch(name)
+        if data is not None:
+            if str(data.get("kind")) == "credential":
+                raise InvalidInput(
+                    f'asset {name!r} is a credential — use "name.field" or asset.credential',
+                    param="name",
+                    input_value=name,
+                )
+            return str(data.get("value") or "")
+        if "." in name:
+            base, _, field = name.rpartition(".")
+            parent = self._fetch(base)
+            fields = (parent or {}).get("fields")
+            if isinstance(fields, dict) and field in fields:
+                return str(fields[field])
+        raise InvalidInput(f"Unknown asset {name!r}", param="name", input_value=name)
+
+    def credential(self, name: str) -> dict[str, str]:
+        data = self._fetch(name)
+        if data is None and "." in name:
+            data = self._fetch(name.rpartition(".")[0])
+        if data is None:
+            raise InvalidInput(f"Unknown asset {name!r}", param="name", input_value=name)
+        if str(data.get("kind")) == "credential":
+            fields = data.get("fields") or {}
+            if isinstance(fields, dict):
+                return {str(key): str(value) for key, value in fields.items()}
+            return {}
+        return {"value": str(data.get("value") or "")}
+
+
+def asset_provider_from_env() -> AssetProvider:
+    """Orchestrator-backed provider when configured, else env vars.
+
+    The agent sets ``R2FLOW_ORCHESTRATOR_URL`` / ``R2FLOW_AGENT_ID`` /
+    ``R2FLOW_AGENT_TOKEN``; self-host runs use ``R2FLOW_ASSET_*`` directly.
+    """
+    url = os.environ.get("R2FLOW_ORCHESTRATOR_URL")
+    agent_id = os.environ.get("R2FLOW_AGENT_ID")
+    token = os.environ.get("R2FLOW_AGENT_TOKEN") or os.environ.get("R2FLOW_API_TOKEN")
+    process_id = os.environ.get("R2FLOW_PROCESS_ID") or None
+    if url and agent_id and token:
+        return HttpAssetProvider(url, agent_id=agent_id, token=token, process_id=process_id)
+    return EnvAssetProvider()

r2flow/core/blocking.py

@@ -0,0 +1,185 @@
+"""Offload blocking calls to a worker thread with a hard timeout.
+
+UIA/COM calls can hang indefinitely (dead dialogs, stalled COM apartments).
+Every blocking offload in the windows tools goes through :func:`run_blocking`,
+which bounds the wait: default 30 s, tunable via the ``R2FLOW_BLOCKING_TIMEOUT``
+environment variable. A timeout raises :class:`PlatformError` instead of
+leaving the bot blocked forever.
+
+COM threading model
+-------------------
+
+UIA elements are apartment-bound COM objects: using a pointer created in
+one thread's apartment from another thread (or after that apartment is
+torn down) fails with ``E_FAIL`` or crashes with an access violation.
+``uiautomation``'s official guidance is equally strict — "you can't use
+a Control created in a different thread".
+
+Therefore all blocking UIA work runs on a single, long-lived worker
+thread that owns one COM apartment (initialized once via
+``CoInitializeEx``). UIA elements are created and consumed on that same
+thread, so they never cross apartments. The trade-off is serialization —
+irrelevant in practice because bot and flow code is sequential.
+
+If a call hangs past *timeout*, the thread is abandoned in place (a hung
+COM call is not interruptible) and the executor is replaced before the
+next call, so one dead dialog cannot poison every subsequent tool call.
+Abandoned threads are joined at interpreter exit.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import os
+import threading
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, TypeVar
+
+from r2flow.core.errors import PlatformError
+
+_T = TypeVar("_T")
+
+_executor_lock = threading.Lock()
+_executor: ThreadPoolExecutor | None = None
+_active_calls = 0
+
+
+def _default_timeout() -> float:
+    raw = os.environ.get("R2FLOW_BLOCKING_TIMEOUT", "30")
+    try:
+        value = float(raw)
+    except ValueError:
+        return 30.0
+    return value if value > 0 else 30.0
+
+
+def _com_thread_init() -> None:
+    """Initialize this worker thread's COM apartment (once per thread)."""
+    try:
+        import comtypes
+    except Exception:  # pragma: no cover — non-Windows
+        return
+    comtypes.CoInitializeEx()
+
+
+def _run_with_com(fn: Callable[..., Any], /, *args: Any, **kwargs: Any) -> Any:
+    """Run *fn* with a COM apartment initialized in the current thread.
+
+    For callers outside the shared worker thread (e.g. the synchronous
+    CLI capture path on the main thread). A no-op when ``comtypes`` is
+    unavailable (non-Windows hosts).
+    """
+    try:
+        import comtypes
+    except Exception:  # pragma: no cover — non-Windows
+        return fn(*args, **kwargs)
+    comtypes.CoInitializeEx()
+    try:
+        return fn(*args, **kwargs)
+    finally:
+        comtypes.CoUninitialize()
+
+
+def _get_executor() -> ThreadPoolExecutor:
+    """The shared single-thread executor (created on first use)."""
+    global _executor
+    with _executor_lock:
+        if _executor is None:
+            _executor = ThreadPoolExecutor(
+                max_workers=1,
+                thread_name_prefix="r2flow-blocking",
+                initializer=_com_thread_init,
+            )
+        return _executor
+
+
+def _abandon_executor() -> bool:
+    """Drop the executor after a hung call (a fresh one is made lazily).
+
+    Only safe when this call is the sole user of the executor: abandoning
+    it shuts down pending/running futures, so concurrent calls would see
+    ``CancelledError`` or ``RuntimeError``. Returns True when the executor
+    was actually abandoned.
+    """
+    global _executor
+    with _executor_lock:
+        if _executor is None or _active_calls > 1:
+            return False
+        executor, _executor = _executor, None
+    executor.shutdown(wait=False)
+    return True
+
+
+def _enter_call() -> None:
+    global _active_calls
+    with _executor_lock:
+        _active_calls += 1
+
+
+def _exit_call() -> None:
+    global _active_calls
+    with _executor_lock:
+        _active_calls -= 1
+
+
+async def run_on_uia_thread(fn: Callable[..., _T], /, *args: Any, **kwargs: Any) -> _T:
+    """Run ``fn(*args, **kwargs)`` on the shared UIA thread — no timeout.
+
+    For interactive flows (e.g. waiting for a human to press CTRL during
+    dev capture) that legitimately take longer than any sane timeout.
+    Uses the same apartment-bound thread as :func:`run_blocking`, so
+    everything it touches shares the process-wide COM apartment.
+    """
+    loop = asyncio.get_running_loop()
+    _enter_call()
+    try:
+        future = loop.run_in_executor(_get_executor(), functools.partial(fn, *args, **kwargs))
+        return await future
+    finally:
+        _exit_call()
+
+
+async def run_blocking(
+    fn: Callable[..., Any],
+    /,
+    *args: Any,
+    timeout: float | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Run ``fn(*args, **kwargs)`` on the shared UIA worker thread.
+
+    The thread owns a COM apartment for the whole process lifetime, so
+    UIA elements created by one call stay valid for the next. After a
+    timeout the thread is abandoned (hung calls are not interruptible)
+    and the next call gets a fresh thread — but only when no other call
+    is in flight, so a timeout can never cancel a concurrent call.
+
+    Raises:
+        PlatformError: If the call does not finish within *timeout* seconds
+            (default: ``R2FLOW_BLOCKING_TIMEOUT`` env var, else 30 s).
+    """
+    limit = timeout if timeout is not None else _default_timeout()
+    loop = asyncio.get_running_loop()
+    _enter_call()
+    try:
+        executor = _get_executor()
+        try:
+            future = loop.run_in_executor(executor, functools.partial(fn, *args, **kwargs))
+        except RuntimeError:
+            # The executor was abandoned between _get_executor and submit
+            # (only possible if a concurrent call timed out). Retry once
+            # against the fresh executor.
+            executor = _get_executor()
+            future = loop.run_in_executor(executor, functools.partial(fn, *args, **kwargs))
+        return await asyncio.wait_for(future, limit)
+    except TimeoutError as exc:
+        _abandon_executor()
+        name = getattr(fn, "__qualname__", None) or repr(fn)
+        raise PlatformError(
+            f"blocking call {name} timed out after {limit:g}s "
+            "(tune R2FLOW_BLOCKING_TIMEOUT if this is expected)",
+        ) from exc
+    finally:
+        _exit_call()