@clawpump/claw-agent 0.1.5 → 0.1.6

package/agent/package.json

@@ -4,10 +4,23 @@
   "description": "An AI agent with advanced tool-calling capabilities, featuring a flexible toolsets system for organizing and managing tools.",
   "private": true,
   "workspaces": [
-    "apps/*"
+    "apps/*",
+    "ui-tui",
+    "ui-tui/packages/*",
+    "web"
   ],
   "scripts": {
-    "postinstall": "echo '✅ Browser tools ready. Run: python run_agent.py --help'"
+    "postinstall": "echo '✅ Browser tools ready. Run: python run_agent.py --help'",
+    "install:root": "npm install --workspaces=false",
+    "install:web": "npm install --workspace web",
+    "install:tui": "npm install --workspace ui-tui",
+    "install:desktop": "npm install --workspace apps/desktop",
+    "audit:root": "npm audit --workspaces=false",
+    "audit:web": "npm audit --workspace web",
+    "audit:tui": "npm audit --workspace ui-tui",
+    "audit:fix:root": "npm audit fix --workspaces=false",
+    "audit:fix:web": "npm audit fix --workspace web",
+    "audit:fix:tui": "npm audit fix --workspace ui-tui"
   },
   "repository": {
     "type": "git",
@@ -23,7 +36,9 @@
     "agent-browser": "^0.26.0"
   },
   "overrides": {
-    "lodash": "4.18.1"
+    "lodash": "4.18.1",
+    "@assistant-ui/store": "0.2.13",
+    "yauzl": "^3.3.1"
   },
   "engines": {
     "node": ">=20.0.0"

package/agent/plugins/browser/firecrawl/provider.py

@@ -78,7 +78,10 @@ class FirecrawlBrowserProvider(BrowserProvider):
         }
 
     def create_session(self, task_id: str) -> Dict[str, object]:
-        ttl = int(os.environ.get("FIRECRAWL_BROWSER_TTL", "300"))
+        try:
+            ttl = int(os.environ.get("FIRECRAWL_BROWSER_TTL", "300"))
+        except (ValueError, TypeError):
+            ttl = 300
 
         body: Dict[str, object] = {"ttl": ttl}
 

package/agent/plugins/cron/__init__.py

@@ -0,0 +1,344 @@
+"""Cron scheduler provider plugin discovery.
+
+Scans two directories for cron scheduler provider plugins:
+
+1. Bundled providers: ``plugins/cron/<name>/`` (shipped with hermes-agent)
+2. User-installed providers: ``$HERMES_HOME/plugins/<name>/``
+
+Each subdirectory must contain ``__init__.py`` with a class implementing the
+``CronScheduler`` ABC (``cron/scheduler_provider.py``). On name collisions,
+bundled providers take precedence.
+
+This is a near-verbatim clone of ``plugins/memory/__init__.py`` — the same
+discovery/loader machinery, retargeted at ``CronScheduler``. The built-in
+``InProcessCronScheduler`` is NOT discovered here: it is core (lives in
+``cron/scheduler_provider.py``) so the fallback can never be accidentally
+removed. Only NON-default providers (e.g. "chronos") live under this directory.
+
+Only ONE provider can be active at a time, selected via ``cron.provider`` in
+config.yaml (empty = built-in). See ``cron.scheduler_provider.resolve_cron_scheduler``.
+
+Usage:
+    from plugins.cron import discover_cron_schedulers, load_cron_scheduler
+
+    available = discover_cron_schedulers()   # [(name, desc, available), ...]
+    provider = load_cron_scheduler("chronos")  # CronScheduler instance
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.machinery
+import importlib.util
+import logging
+import sys
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+_CRON_PLUGINS_DIR = Path(__file__).parent
+
+# Synthetic parent package for user-installed providers, so they don't
+# collide with bundled providers in sys.modules.
+_USER_NAMESPACE = "_hermes_user_cron"
+
+
+def _register_synthetic_package(name: str, search_locations: List[str]) -> None:
+    """Register an empty package shell in sys.modules.
+
+    User-installed providers import as ``_hermes_user_cron.<name>``, a dotted
+    name whose parents exist nowhere on disk. Unless those parents are present
+    in ``sys.modules``, any relative import inside the plugin
+    (``from . import config``) fails with
+    ``ModuleNotFoundError: No module named '_hermes_user_cron'`` — the same
+    reason the loader already registers ``plugins`` and ``plugins.cron`` for
+    bundled providers.
+    """
+    if name in sys.modules:
+        return
+    spec = importlib.machinery.ModuleSpec(name, None, is_package=True)
+    spec.submodule_search_locations = search_locations
+    sys.modules[name] = importlib.util.module_from_spec(spec)
+
+
+# ---------------------------------------------------------------------------
+# Directory helpers
+# ---------------------------------------------------------------------------
+
+def _get_user_plugins_dir() -> Optional[Path]:
+    """Return ``$HERMES_HOME/plugins/`` or None if unavailable."""
+    try:
+        from hermes_constants import get_hermes_home
+        d = get_hermes_home() / "plugins"
+        return d if d.is_dir() else None
+    except Exception:
+        return None
+
+
+def _is_cron_provider_dir(path: Path) -> bool:
+    """Heuristic: does *path* look like a cron scheduler provider plugin?
+
+    Checks for ``register_cron_scheduler`` or ``CronScheduler`` in the
+    ``__init__.py`` source. Cheap text scan — no import needed.
+    """
+    init_file = path / "__init__.py"
+    if not init_file.exists():
+        return False
+    try:
+        source = init_file.read_text(errors="replace")[:8192]
+        return "register_cron_scheduler" in source or "CronScheduler" in source
+    except Exception:
+        return False
+
+
+def _iter_provider_dirs() -> List[Tuple[str, Path]]:
+    """Yield ``(name, path)`` for all discovered provider directories.
+
+    Scans bundled first, then user-installed. Bundled takes precedence on
+    name collisions (first-seen wins via ``seen`` set).
+    """
+    seen: set = set()
+    dirs: List[Tuple[str, Path]] = []
+
+    # 1. Bundled providers (plugins/cron/<name>/)
+    if _CRON_PLUGINS_DIR.is_dir():
+        for child in sorted(_CRON_PLUGINS_DIR.iterdir()):
+            if not child.is_dir() or child.name.startswith(("_", ".")):
+                continue
+            if not (child / "__init__.py").exists():
+                continue
+            seen.add(child.name)
+            dirs.append((child.name, child))
+
+    # 2. User-installed providers ($HERMES_HOME/plugins/<name>/)
+    user_dir = _get_user_plugins_dir()
+    if user_dir:
+        for child in sorted(user_dir.iterdir()):
+            if not child.is_dir() or child.name.startswith(("_", ".")):
+                continue
+            if child.name in seen:
+                continue  # bundled takes precedence
+            if not _is_cron_provider_dir(child):
+                continue  # skip non-cron plugins
+            dirs.append((child.name, child))
+
+    return dirs
+
+
+def find_provider_dir(name: str) -> Optional[Path]:
+    """Resolve a provider name to its directory.
+
+    Checks bundled first, then user-installed.
+    """
+    # Bundled
+    bundled = _CRON_PLUGINS_DIR / name
+    if bundled.is_dir() and (bundled / "__init__.py").exists():
+        return bundled
+    # User-installed
+    user_dir = _get_user_plugins_dir()
+    if user_dir:
+        user = user_dir / name
+        if user.is_dir() and _is_cron_provider_dir(user):
+            return user
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def discover_cron_schedulers() -> List[Tuple[str, str, bool]]:
+    """Scan bundled and user-installed directories for available providers.
+
+    Returns list of (name, description, is_available) tuples. May be empty —
+    the built-in is core, not discovered here, so a fresh checkout with no
+    bundled non-default provider returns []. Bundled providers take precedence
+    on name collisions.
+    """
+    results = []
+
+    for name, child in _iter_provider_dirs():
+        # Read description from plugin.yaml if available
+        desc = ""
+        yaml_file = child / "plugin.yaml"
+        if yaml_file.exists():
+            try:
+                import yaml
+                with open(yaml_file, encoding="utf-8-sig") as f:
+                    meta = yaml.safe_load(f) or {}
+                desc = meta.get("description", "")
+            except Exception:
+                pass
+
+        # Quick availability check — try loading and calling is_available()
+        available = True
+        try:
+            provider = _load_provider_from_dir(child)
+            if provider:
+                available = provider.is_available()
+            else:
+                available = False
+        except Exception:
+            available = False
+
+        results.append((name, desc, available))
+
+    return results
+
+
+def load_cron_scheduler(name: str) -> Optional["CronScheduler"]:  # noqa: F821
+    """Load and return a CronScheduler instance by name.
+
+    Checks both bundled (``plugins/cron/<name>/``) and user-installed
+    (``$HERMES_HOME/plugins/<name>/``) directories. Bundled takes precedence
+    on name collisions.
+
+    Returns None if the provider is not found or fails to load.
+    """
+    provider_dir = find_provider_dir(name)
+    if not provider_dir:
+        logger.debug("Cron provider '%s' not found in bundled or user plugins", name)
+        return None
+
+    try:
+        provider = _load_provider_from_dir(provider_dir)
+        if provider:
+            return provider
+        logger.warning("Cron provider '%s' loaded but no provider instance found", name)
+        return None
+    except Exception as e:
+        logger.warning("Failed to load cron provider '%s': %s", name, e)
+        return None
+
+
+def _load_provider_from_dir(provider_dir: Path) -> Optional["CronScheduler"]:  # noqa: F821
+    """Import a provider module and extract the CronScheduler instance.
+
+    The module must have either:
+    - A register(ctx) function (plugin-style) — we simulate a ctx
+    - A top-level class that extends CronScheduler — we instantiate it
+    """
+    name = provider_dir.name
+    # Use a separate namespace for user-installed plugins so they don't
+    # collide with bundled providers in sys.modules.
+    _is_bundled = _CRON_PLUGINS_DIR in provider_dir.parents or provider_dir.parent == _CRON_PLUGINS_DIR
+    module_name = f"plugins.cron.{name}" if _is_bundled else f"{_USER_NAMESPACE}.{name}"
+    init_file = provider_dir / "__init__.py"
+
+    if not init_file.exists():
+        return None
+
+    # Check if already loaded. A synthetic package shell has no __file__;
+    # only reuse modules that were actually loaded from disk.
+    cached = sys.modules.get(module_name)
+    if cached is not None and getattr(cached, "__file__", None):
+        mod = cached
+    else:
+        # Ensure the parent packages are registered (for relative imports)
+        for parent in ("plugins", "plugins.cron"):
+            if parent not in sys.modules:
+                parent_path = Path(__file__).parent
+                if parent == "plugins":
+                    parent_path = parent_path.parent
+                parent_init = parent_path / "__init__.py"
+                if parent_init.exists():
+                    spec = importlib.util.spec_from_file_location(
+                        parent, str(parent_init),
+                        submodule_search_locations=[str(parent_path)]
+                    )
+                    if spec:
+                        parent_mod = importlib.util.module_from_spec(spec)
+                        sys.modules[parent] = parent_mod
+                        try:
+                            spec.loader.exec_module(parent_mod)
+                        except Exception:
+                            pass
+
+        # User-installed plugins need their synthetic parent registered the
+        # same way, or relative imports inside the plugin cannot resolve.
+        if not _is_bundled:
+            _register_synthetic_package(_USER_NAMESPACE, [])
+
+        # Now load the provider module
+        spec = importlib.util.spec_from_file_location(
+            module_name, str(init_file),
+            submodule_search_locations=[str(provider_dir)]
+        )
+        if not spec:
+            return None
+
+        mod = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = mod
+
+        # Register submodules so relative imports work
+        # e.g., "from ._nas_client import NasCronClient" in the chronos plugin
+        for sub_file in provider_dir.glob("*.py"):
+            if sub_file.name == "__init__.py":
+                continue
+            sub_name = sub_file.stem
+            full_sub_name = f"{module_name}.{sub_name}"
+            if full_sub_name not in sys.modules:
+                sub_spec = importlib.util.spec_from_file_location(
+                    full_sub_name, str(sub_file)
+                )
+                if sub_spec:
+                    sub_mod = importlib.util.module_from_spec(sub_spec)
+                    sys.modules[full_sub_name] = sub_mod
+                    try:
+                        sub_spec.loader.exec_module(sub_mod)
+                    except Exception as e:
+                        logger.debug("Failed to load submodule %s: %s", full_sub_name, e)
+
+        try:
+            spec.loader.exec_module(mod)
+        except Exception as e:
+            logger.debug("Failed to exec_module %s: %s", module_name, e)
+            sys.modules.pop(module_name, None)
+            return None
+
+    # Try register(ctx) pattern first (how our plugins are written)
+    if hasattr(mod, "register"):
+        collector = _ProviderCollector()
+        try:
+            mod.register(collector)
+            if collector.provider:
+                return collector.provider
+        except Exception as e:
+            logger.debug("register() failed for %s: %s", name, e)
+
+    # Fallback: find a CronScheduler subclass and instantiate it
+    from cron.scheduler_provider import CronScheduler
+    for attr_name in dir(mod):
+        attr = getattr(mod, attr_name, None)
+        if (isinstance(attr, type) and issubclass(attr, CronScheduler)
+                and attr is not CronScheduler):
+            try:
+                return attr()
+            except Exception:
+                pass
+
+    return None
+
+
+class _ProviderCollector:
+    """Fake plugin context that captures register_cron_scheduler calls."""
+
+    def __init__(self):
+        self.provider = None
+
+    def register_cron_scheduler(self, provider):
+        self.provider = provider
+
+    # No-op for other registration methods
+    def register_tool(self, *args, **kwargs):
+        pass
+
+    def register_hook(self, *args, **kwargs):
+        pass
+
+    def register_memory_provider(self, *args, **kwargs):
+        pass
+
+    def register_cli_command(self, *args, **kwargs):
+        pass

package/agent/plugins/cron/chronos/__init__.py

@@ -0,0 +1,241 @@
+"""Chronos — NAS-mediated managed cron provider (scale-to-zero).
+
+Chronos (the Greek god of time, alongside Hermes) is the first non-default
+``CronScheduler``. It lets a hosted gateway scale to zero while idle and still
+fire cron jobs: instead of a 60s in-process ticker, it asks NAS to arm exactly
+one external one-shot per job at that job's real next-fire time. NAS calls the
+agent back at fire time over an authenticated webhook (``/api/cron/fire``); the
+agent runs the job via the shared ``run_one_job`` body and re-arms the next
+one-shot.
+
+The external scheduler NAS uses is an internal NAS implementation detail —
+Chronos names no vendor, holds no scheduler credentials, and speaks only to
+NAS's ``agent-cron`` endpoints with the agent's existing Nous token.
+
+Design constraints (see the plan's DQ-1):
+  - start() arms all enabled jobs and RETURNS; it never blocks and never spawns
+    a periodic wake. Between fires the machine is truly at zero.
+  - reconcile runs only on a warm process (start / on_jobs_changed / piggybacked
+    on a fire), never as a periodic wake of a sleeping machine.
+
+Inert unless ``cron.provider: chronos``. ``resolve_cron_scheduler`` falls back
+to the built-in if Chronos is unavailable, so cron never loses its trigger.
+
+Wire contract: ``docs/chronos-managed-cron-contract.md``.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any, Dict, Optional
+
+from cron.scheduler_provider import CronScheduler
+
+logger = logging.getLogger("cron.chronos")
+
+
+def _cfg(*keys: str, default: Any = "") -> Any:
+    """Read a cron.chronos.* config value (no network)."""
+    try:
+        from hermes_cli.config import cfg_get, load_config
+        return cfg_get(load_config(), *keys, default=default)
+    except Exception:
+        return default
+
+
+class ChronosCronScheduler(CronScheduler):
+    """NAS-mediated external cron provider."""
+
+    def __init__(self) -> None:
+        # In-memory map of job_id → fire_at we've asked NAS to arm. Best-effort
+        # cache; reconcile rebuilds desired state from jobs.json, so a cold
+        # process simply re-arms (idempotent via dedup_key).
+        self._armed: Dict[str, str] = {}
+        self._lock = threading.Lock()
+        self._client = None  # lazily constructed (no network in is_available)
+
+    # -- identity / availability -----------------------------------------
+
+    @property
+    def name(self) -> str:
+        return "chronos"
+
+    def is_available(self) -> bool:
+        """Config presence only — NO network.
+
+        Chronos needs a portal base URL, the agent's own publicly-reachable
+        callback URL (for NAS→agent fires), and a usable Nous token (the agent
+        is logged into the portal). If any is missing, resolve_cron_scheduler
+        falls back to the built-in ticker.
+        """
+        if not (_cfg("cron", "chronos", "portal_url") and _cfg("cron", "chronos", "callback_url")):
+            return False
+        return self._have_nous_token()
+
+    def _have_nous_token(self) -> bool:
+        """True if the agent has a Nous Portal login (no network call).
+
+        Checks the stored auth state for a Nous access token — does NOT refresh
+        or hit the network (is_available must stay offline). The actual
+        refresh-aware token is resolved lazily at provision time.
+        """
+        try:
+            from hermes_cli.auth import get_provider_auth_state
+            state = get_provider_auth_state("nous") or {}
+            return bool(state.get("access_token"))
+        except Exception:
+            return False
+
+    # -- client -----------------------------------------------------------
+
+    def _get_client(self):
+        if self._client is None:
+            from ._nas_client import NasCronClient
+            self._client = NasCronClient(_cfg("cron", "chronos", "portal_url"))
+        return self._client
+
+    def _callback_url(self) -> str:
+        return str(_cfg("cron", "chronos", "callback_url") or "")
+
+    # -- lifecycle --------------------------------------------------------
+
+    def start(self, stop_event, *, adapters=None, loop=None, interval=60):
+        """Arm all enabled jobs via NAS, then RETURN immediately.
+
+        Does NOT block and does NOT spawn a 60s wake (DQ-1) — that is the whole
+        point of scale-to-zero. The machine wakes only on a NAS→agent fire.
+        """
+        try:
+            self.reconcile()
+        except Exception as e:
+            logger.warning("Chronos start() reconcile failed: %s", e)
+        # Intentionally return — no loop, no periodic wake.
+
+    def stop(self) -> None:
+        return None
+
+    def on_jobs_changed(self) -> None:
+        """A job was created/updated/removed/paused/resumed — reconcile the NAS
+        registry so the affected one-shot is (re-)armed or cancelled."""
+        try:
+            self.reconcile()
+        except Exception as e:
+            logger.debug("Chronos on_jobs_changed reconcile failed: %s", e)
+
+    # -- arming -----------------------------------------------------------
+
+    def _arm_one_shot(self, job: Dict[str, Any]) -> None:
+        """Ask NAS to arm exactly one one-shot at the job's next_run_at.
+
+        The agent computes the time; NAS+its scheduler are the dumb executor.
+        Idempotent per (job_id, fire_at) via dedup_key, so re-arming the same
+        fire is a no-op NAS-side.
+        """
+        job_id = job["id"]
+        fire_at = job.get("next_run_at")
+        if not fire_at:
+            return
+        dedup_key = f"{job_id}:{fire_at}"
+        self._get_client().provision(
+            job_id=job_id,
+            fire_at=fire_at,
+            agent_callback_url=self._callback_url(),
+            dedup_key=dedup_key,
+        )
+        with self._lock:
+            self._armed[job_id] = fire_at
+
+    def _cancel(self, job_id: str) -> None:
+        try:
+            self._get_client().cancel(job_id=job_id)
+        finally:
+            with self._lock:
+                self._armed.pop(job_id, None)
+
+    def _list_armed(self) -> Dict[str, str]:
+        """Observed armed one-shots: job_id → fire_at.
+
+        Prefer the in-memory map (warm process); on a cold/empty map, ask NAS
+        (best-effort). If NAS list fails, return what we have — reconcile then
+        re-arms desired jobs idempotently.
+        """
+        with self._lock:
+            if self._armed:
+                return dict(self._armed)
+        try:
+            observed = {
+                item["job_id"]: item.get("fire_at", "")
+                for item in self._get_client().list_armed()
+                if item.get("job_id")
+            }
+            with self._lock:
+                self._armed.update(observed)
+            return observed
+        except Exception as e:
+            logger.debug("Chronos _list_armed failed (will re-arm idempotently): %s", e)
+            return {}
+
+    # -- reconcile --------------------------------------------------------
+
+    def reconcile(self) -> None:
+        """Converge the NAS-armed one-shots toward jobs.json (desired state):
+        arm missing / re-arm changed-time, cancel orphaned."""
+        from cron.jobs import load_jobs
+
+        desired: Dict[str, str] = {
+            j["id"]: j["next_run_at"]
+            for j in load_jobs()
+            if j.get("enabled") and j.get("next_run_at") and j.get("state") != "paused"
+        }
+        observed = self._list_armed()
+
+        # Arm missing or changed-time.
+        for job_id, fire_at in desired.items():
+            if observed.get(job_id) != fire_at:
+                # Re-fetch the full job dict to arm (need the whole record).
+                from cron.jobs import get_job
+                job = get_job(job_id)
+                if job:
+                    try:
+                        self._arm_one_shot(job)
+                    except Exception as e:
+                        logger.warning("Chronos failed to arm job %s: %s", job_id, e)
+
+        # Cancel orphans (armed but no longer desired).
+        for job_id in list(observed.keys()):
+            if job_id not in desired:
+                try:
+                    self._cancel(job_id)
+                except Exception as e:
+                    logger.warning("Chronos failed to cancel orphan %s: %s", job_id, e)
+
+    # -- fire -------------------------------------------------------------
+
+    def fire_due(self, job_id: str, *, adapters: Any = None, loop: Any = None) -> bool:
+        """Run the due job (claim + run_one_job via the ABC default), then
+        re-arm the NEXT one-shot through NAS.
+
+        Re-arm happens AFTER the run so next_run_at reflects the completed fire.
+        If the job is gone (one-shot completed / repeat-N exhausted), get_job
+        returns None → nothing to re-arm (the schedule naturally stops).
+        """
+        ran = super().fire_due(job_id, adapters=adapters, loop=loop)
+        if ran:
+            from cron.jobs import get_job
+            job = get_job(job_id)
+            if job and job.get("enabled") and job.get("next_run_at"):
+                try:
+                    self._arm_one_shot(job)
+                except Exception as e:
+                    logger.warning("Chronos failed to re-arm job %s after fire: %s", job_id, e)
+        return ran
+
+
+def register(ctx) -> None:
+    """Plugin entrypoint — register the Chronos provider with the loader.
+
+    Mirrors the memory-plugin shape; plugins/cron discovery calls this and
+    collects the provider via register_cron_scheduler.
+    """
+    ctx.register_cron_scheduler(ChronosCronScheduler())