@clawpump/claw-agent 0.1.5 → 0.1.7

package/agent/cron/scheduler_provider.py

@@ -0,0 +1,177 @@
+"""CronScheduler provider interface (Axis B — the trigger).
+
+⚠️ EXPERIMENTAL — this interface is validated by exactly ONE consumer (the
+built-in) until an external provider (Chronos, Phase 4) shakes it out. Until
+then the module path, method signatures, and start() kwargs MAY change without
+a deprecation cycle. Once a second provider validates the shape it becomes
+stable. Any growth MUST be additive (new optional method with a default), never
+a changed signature on start() or a new abstractmethod.
+
+A CronScheduler decides *when* a due job fires. It does NOT decide what firing
+means: execution + delivery stay in cron.scheduler.run_job / _deliver_result,
+shared by all providers. Providers must never reimplement agent construction or
+delivery.
+
+The built-in InProcessCronScheduler runs the historical 60s daemon-thread
+ticker. Alternative providers (e.g. Chronos, a NAS-mediated managed-cron
+provider for scale-to-zero deployments) live under plugins/cron/<name>/ and are
+selected via the `cron.provider` config key (empty = built-in).
+"""
+from __future__ import annotations
+
+import threading
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class CronScheduler(ABC):
+    """Axis-B trigger provider. Decides WHEN a due cron job fires.
+
+    Required surface is intentionally minimal: ``name`` + ``start``. ``stop``
+    and ``is_available`` carry safe defaults. The three Phase-4 hooks
+    (``on_jobs_changed`` / ``fire_due`` / ``reconcile``) are added later as
+    NON-abstract methods so the built-in keeps satisfying the ABC without
+    overriding them — see ``test_abc_growth_stays_additive``.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Short identifier, e.g. 'builtin', 'chronos'."""
+
+    def is_available(self) -> bool:
+        """Whether this provider can run in the current environment.
+
+        MUST NOT make network calls. The built-in is always available; an
+        external provider checks for configured endpoint/credentials. When a
+        named provider returns False, the resolver falls back to the built-in.
+        """
+        return True
+
+    @abstractmethod
+    def start(
+        self,
+        stop_event: threading.Event,
+        *,
+        adapters: Any = None,
+        loop: Any = None,
+        interval: int = 60,
+    ) -> None:
+        """Begin firing due jobs.
+
+        For the built-in this BLOCKS in the 60s loop until stop_event is set
+        (it is run inside a daemon thread by the caller, exactly as today).
+        An external provider may register a schedule/webhook and return
+        immediately; in that case it must still honor stop_event for teardown.
+        """
+
+    def stop(self) -> None:
+        """Optional eager teardown hook. Default no-op; setting the stop_event
+        is the primary stop signal. Override for providers holding external
+        resources (queue consumers, HTTP servers)."""
+        return None
+
+    # --- Optional hooks for external providers (added Phase 4). --------------
+    # All default-safe so the built-in inherits working behavior without
+    # overriding. Keep these NON-abstract — see test_abc_growth_stays_additive.
+
+    def on_jobs_changed(self) -> None:
+        """Called after a successful store mutation (create/update/remove/
+        pause/resume). External providers reconcile their registry here (e.g.
+        Chronos re-provisions/cancels the affected one-shot via NAS).
+        Built-in: no-op (it re-reads jobs.json on every tick)."""
+        return None
+
+    def fire_due(self, job_id: str, *, adapters: Any = None, loop: Any = None) -> bool:
+        """Run a single job NOW via the shared orchestrator. Called by the
+        inbound fire webhook when an external scheduler signals a job is due.
+
+        The default claims the job with a store-level compare-and-set
+        (multi-machine at-most-once), then runs it via the shared
+        ``run_one_job`` body. Built-in never calls this (it has its own tick
+        loop); an external provider routes its inbound fire here.
+
+        Returns True if THIS caller claimed and ran the job, False if the claim
+        was lost (another machine/retry won it) or the job no longer exists.
+        """
+        from cron.jobs import claim_job_for_fire, get_job
+        from cron.scheduler import run_one_job
+
+        if not claim_job_for_fire(job_id):
+            return False  # another machine already claimed this fire
+        job = get_job(job_id)
+        if job is None:
+            return False  # job removed (e.g. repeat-N exhausted) between arm and fire
+        return run_one_job(job, adapters=adapters, loop=loop)
+
+    def reconcile(self) -> None:
+        """Converge the external registry toward jobs.json (the desired state):
+        arm missing one-shots, cancel orphaned ones, re-arm changed times.
+        Built-in: no-op."""
+        return None
+
+
+def resolve_cron_scheduler() -> "CronScheduler":
+    """Return the active cron scheduler provider.
+
+    Reads ``cron.provider`` from config. Empty/absent → built-in. A named
+    provider that is missing, fails to load, or reports ``is_available() ==
+    False`` falls back to the built-in with a warning — cron must never be left
+    without a trigger.
+    """
+    import logging
+
+    logger = logging.getLogger("cron.scheduler_provider")
+
+    name = ""
+    try:
+        from hermes_cli.config import cfg_get, load_config
+        name = (cfg_get(load_config(), "cron", "provider", default="") or "").strip()
+    except Exception:
+        pass
+
+    if not name or name in ("builtin", "in-process", "inprocess"):
+        return InProcessCronScheduler()
+
+    try:
+        from plugins.cron import load_cron_scheduler
+        provider = load_cron_scheduler(name)
+        if provider is None:
+            logger.warning("cron.provider '%s' not found; using built-in ticker", name)
+            return InProcessCronScheduler()
+        if not provider.is_available():
+            logger.warning("cron.provider '%s' not available; using built-in ticker", name)
+            return InProcessCronScheduler()
+        logger.info("Using cron scheduler provider: %s", provider.name)
+        return provider
+    except Exception as e:
+        logger.warning(
+            "Failed to load cron.provider '%s' (%s); using built-in ticker", name, e
+        )
+        return InProcessCronScheduler()
+
+
+class InProcessCronScheduler(CronScheduler):
+    """Default provider: the historical in-process 60s ticker.
+
+    ``start()`` blocks in the tick loop until ``stop_event`` is set, identical
+    to the pre-refactor ``_start_cron_ticker`` core loop. The caller runs it in
+    a daemon thread.
+    """
+
+    @property
+    def name(self) -> str:
+        return "builtin"
+
+    def start(self, stop_event, *, adapters=None, loop=None, interval=60):
+        import logging
+        from cron.scheduler import tick as cron_tick
+
+        logger = logging.getLogger("cron.scheduler_provider")
+        logger.info("In-process cron scheduler started (interval=%ds)", interval)
+        while not stop_event.is_set():
+            try:
+                cron_tick(verbose=False, adapters=adapters, loop=loop, sync=False)
+            except Exception as e:
+                logger.debug("Cron tick error: %s", e)
+            stop_event.wait(interval)

package/agent/cron/scripts/__init__.py

@@ -0,0 +1 @@
+"""Scripts shipped with the cron subsystem (runnable via ``python3 -m cron.scripts.<name>``)."""

package/agent/cron/scripts/classify_items.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Classify candidate items by urgency/importance and emit only the urgent ones.
+
+The proactive-monitor pattern: a fetch step (a watcher script, an inbox dump, a
+feed) produces a list of candidate items; this script scores each with a cheap
+LLM and prints ONLY the items at or above a threshold. Below-threshold runs
+print nothing, so a cron job wrapping this stays silent unless something
+actually matters -- the classic urgency-monitor pattern (fetch -> classify
+urgency -> surface only what's above the bar).
+
+Design choices:
+  * Uses Hermes' auxiliary client with task="monitor", so the classifier model
+    is configured once in config.yaml (auxiliary.monitor.{provider,model}) and
+    can be a cheap fast model independent of the main chat model.
+  * Reads items as JSON (a list of objects) from stdin or --input-file.
+  * One LLM call scores the whole batch (cheap, single round-trip) and returns
+    structured scores; we filter locally.
+  * Empty result -> empty stdout -> the cron job's [SILENT]/empty-stdout path
+    suppresses delivery. No spam on quiet intervals.
+
+Usage (standalone):
+  cat items.json | python classify_items.py --threshold 7 \
+    --criteria "Urgent if it needs a reply today or is from my manager/family"
+
+Usage (wired to a watcher via cron, agent mode):
+  Ask the agent: "Every 10 minutes, run watch_http_json.py for my inbox feed,
+  pipe its JSON into classify_items.py with my urgency criteria, and deliver
+  whatever it prints. Stay silent if it prints nothing."
+
+Item schema (flexible): each item is an object; the classifier sees the whole
+object. A "title"/"subject"/"summary"/"text" field helps it judge. An "id"
+field (any of id/guid/message_id/url) is echoed back so duplicates can be
+deduped upstream.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+
+def _eprint(*args: Any) -> None:
+    print(*args, file=sys.stderr)
+
+
+def _load_items(input_file: Optional[str]) -> List[Dict[str, Any]]:
+    raw = ""
+    if input_file:
+        with open(input_file, encoding="utf-8") as f:
+            raw = f.read()
+    else:
+        raw = sys.stdin.read()
+    raw = raw.strip()
+    if not raw:
+        return []
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _eprint(f"classify_items: input is not valid JSON: {e}")
+        sys.exit(2)
+    if isinstance(data, dict):
+        # Allow {"items": [...]} or a single object.
+        if isinstance(data.get("items"), list):
+            return data["items"]
+        return [data]
+    if isinstance(data, list):
+        return [x for x in data if isinstance(x, dict)]
+    _eprint("classify_items: expected a JSON list or {items: [...]}")
+    sys.exit(2)
+
+
+def _item_id(item: Dict[str, Any], index: int) -> str:
+    for key in ("id", "guid", "message_id", "url", "link"):
+        val = item.get(key)
+        if val:
+            return str(val)
+    return f"item-{index}"
+
+
+_CLASSIFY_INSTRUCTIONS = (
+    "You are an urgency classifier for a proactive assistant. You will be given "
+    "a numbered list of items and the user's importance criteria. Score EACH "
+    "item from 0 (ignore entirely) to 10 (interrupt the user now). Return ONLY a "
+    "JSON array, one object per item, in the same order: "
+    '[{"index": <int>, "score": <int 0-10>, "reason": "<short>"}]. '
+    "No prose, no markdown fences. Be conservative: most items should score low. "
+    "Only score high when the item clearly meets the user's criteria."
+)
+
+
+def _build_prompt(items: List[Dict[str, Any]], criteria: str) -> str:
+    lines = [f"USER IMPORTANCE CRITERIA:\n{criteria}\n", "ITEMS:"]
+    for i, item in enumerate(items):
+        # Show a compact view; the model sees the salient fields.
+        view = {
+            k: item[k]
+            for k in ("title", "subject", "summary", "text", "body", "from", "sender", "url")
+            if k in item
+        }
+        if not view:
+            view = item  # fall back to the whole object
+        lines.append(f"[{i}] {json.dumps(view, ensure_ascii=False)[:1200]}")
+    lines.append(
+        "\nReturn the JSON array of scores now (one object per item, same order)."
+    )
+    return "\n".join(lines)
+
+
+def _parse_scores(content: str, n_items: int) -> Dict[int, Dict[str, Any]]:
+    text = (content or "").strip()
+    # Tolerate accidental markdown fences.
+    if text.startswith("```"):
+        text = text.strip("`")
+        if "\n" in text:
+            text = text.split("\n", 1)[1]
+    try:
+        arr = json.loads(text)
+    except json.JSONDecodeError:
+        # Last-ditch: find the first [...] block.
+        start = text.find("[")
+        end = text.rfind("]")
+        if start >= 0 and end > start:
+            try:
+                arr = json.loads(text[start : end + 1])
+            except json.JSONDecodeError:
+                _eprint("classify_items: could not parse classifier output")
+                return {}
+        else:
+            _eprint("classify_items: classifier returned no JSON array")
+            return {}
+    out: Dict[int, Dict[str, Any]] = {}
+    if isinstance(arr, list):
+        for obj in arr:
+            if not isinstance(obj, dict):
+                continue
+            idx = obj.get("index")
+            if isinstance(idx, int) and 0 <= idx < n_items:
+                out[idx] = obj
+    return out
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Classify items by urgency; emit only urgent ones.")
+    parser.add_argument("--criteria", required=True, help="Plain-language importance criteria.")
+    parser.add_argument("--threshold", type=int, default=7, help="Minimum score (0-10) to surface. Default 7.")
+    parser.add_argument("--input-file", default=None, help="Read items JSON from this file instead of stdin.")
+    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format for surfaced items.")
+    args = parser.parse_args()
+
+    items = _load_items(args.input_file)
+    if not items:
+        # Nothing to classify -> silent. This is the common quiet-interval case.
+        return 0
+
+    # Import here so --help works without the package importable.
+    try:
+        from agent.auxiliary_client import call_llm
+    except Exception as e:  # pragma: no cover - import guard
+        _eprint(f"classify_items: cannot import auxiliary client: {e}")
+        return 3
+
+    prompt = _build_prompt(items, args.criteria)
+    try:
+        resp = call_llm(
+            task="monitor",
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=1024,
+            temperature=0,
+        )
+        content = resp.choices[0].message.content
+        if not isinstance(content, str):
+            content = str(content) if content else ""
+    except Exception as e:
+        # Classification failure is NOT silent -- surface it so a broken monitor
+        # doesn't quietly swallow important items. Non-zero exit -> cron alerts.
+        _eprint(f"classify_items: classifier call failed: {e}")
+        return 4
+
+    scores = _parse_scores(content, len(items))
+    surfaced = []
+    for i, item in enumerate(items):
+        s = scores.get(i)
+        score = s.get("score") if isinstance(s, dict) else None
+        if isinstance(score, int) and score >= args.threshold:
+            surfaced.append((i, item, s))
+
+    if not surfaced:
+        # Below threshold -> silent. Empty stdout; cron suppresses delivery.
+        return 0
+
+    if args.format == "json":
+        out = [
+            {
+                "id": _item_id(item, i),
+                "score": s.get("score"),
+                "reason": s.get("reason", ""),
+                "item": item,
+            }
+            for (i, item, s) in surfaced
+        ]
+        print(json.dumps(out, ensure_ascii=False, indent=2))
+    else:
+        blocks = []
+        for (i, item, s) in surfaced:
+            title = (
+                item.get("title")
+                or item.get("subject")
+                or item.get("summary")
+                or _item_id(item, i)
+            )
+            url = item.get("url") or item.get("link") or ""
+            reason = s.get("reason", "")
+            block = f"## [{s.get('score')}/10] {title}"
+            if url:
+                block += f"\n{url}"
+            if reason:
+                block += f"\n_{reason}_"
+            blocks.append(block)
+        print("\n\n".join(blocks))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/agent/cron/suggestion_catalog.py

@@ -0,0 +1,154 @@
+"""Curated catalog of starter cron-job suggestions.
+
+These are the built-in automations Hermes can offer a new user out of the box —
+the ``catalog`` source of the unified suggestion surface. Each entry is a
+ready-to-run ``cron.jobs.create_job`` spec wrapped as a suggestion; the user
+accepts via ``/suggestions``. Nothing here auto-schedules.
+
+The "important-mail monitor" entry is where the old proactive-monitor engine
+lives now: its ``classify_items.py`` (poll a source -> LLM-score urgency ->
+surface only above-threshold) is ONE catalog automation, not a standalone
+feature.
+
+Adding a catalog entry: append a CatalogEntry. Keep prompts self-contained
+(cron jobs run with no chat context) and schedules sensible. The ``job_spec``
+is passed verbatim to ``create_job`` on accept.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+__all__ = ["CatalogEntry", "CATALOG", "seed_catalog_suggestions", "classify_items_script_path"]
+
+
+def classify_items_script_path() -> str:
+    """Absolute path to the urgency classifier script shipped with cron/."""
+    return str((Path(__file__).resolve().parent / "scripts" / "classify_items.py"))
+
+
+@dataclass(frozen=True)
+class CatalogEntry:
+    """A curated starter automation offered as a suggestion."""
+
+    key: str                 # stable dedup key (never re-offered once dismissed)
+    title: str
+    description: str
+    job_spec: Dict[str, Any]  # kwargs for cron.jobs.create_job
+
+
+# The curated set. Schedules use the cron/interval syntax create_job accepts.
+CATALOG: List[CatalogEntry] = [
+    CatalogEntry(
+        key="catalog:daily-briefing",
+        title="Daily briefing",
+        description="Every morning at 8am, a short briefing: today's calendar, "
+        "weather, and anything urgent waiting on you.",
+        job_spec={
+            "prompt": (
+                "Produce a concise morning briefing for the user: today's "
+                "calendar events, the local weather, and any urgent items "
+                "(unread important email, due tasks). Keep it short and "
+                "scannable. If you have no connected data sources, give a brief "
+                "general good-morning with the date and offer to connect "
+                "calendar/email."
+            ),
+            "schedule": "0 8 * * *",
+            "name": "Daily briefing",
+            "deliver": "origin",
+        },
+    ),
+    CatalogEntry(
+        key="catalog:important-mail-monitor",
+        title="Important-mail monitor",
+        description="Check your inbox periodically and ping you ONLY about mail "
+        "that actually needs attention — never the newsletters.",
+        job_spec={
+            "prompt": (
+                "Check the user's inbox for new messages since the last run. "
+                "For each candidate, judge urgency against this rule: surface "
+                "only mail that needs a reply today, is from a manager/family "
+                "member, or mentions a deadline. Pipe candidates through the "
+                "urgency classifier (run `python3 -m cron.scripts.classify_items "
+                "--threshold 7 --criteria ...` from the hermes-agent install — "
+                "resolve the script path at run time, do not assume a fixed "
+                "location) and deliver ONLY what it returns. If nothing "
+                "clears the bar, respond with [SILENT] so the user is not "
+                "pinged. Requires a connected mail source; if none is "
+                "configured, explain how to connect one and then stop."
+            ),
+            "schedule": "every 30m",
+            "name": "Important-mail monitor",
+            "deliver": "origin",
+        },
+    ),
+    CatalogEntry(
+        key="catalog:weekly-review",
+        title="Weekly review",
+        description="Every Sunday evening, a recap of the week: what got done, "
+        "what's still open, and what's coming up next week.",
+        job_spec={
+            "prompt": (
+                "Produce a weekly review for the user: summarize what was "
+                "accomplished this week, list still-open items, and preview "
+                "next week's calendar. Pull from whatever sources are connected "
+                "(calendar, task tools, recent conversations). Keep it tight."
+            ),
+            "schedule": "0 18 * * 0",
+            "name": "Weekly review",
+            "deliver": "origin",
+        },
+    ),
+    CatalogEntry(
+        key="catalog:standup-reminder",
+        title="Workday start reminder",
+        description="A weekday nudge at 9am with your day's agenda and top "
+        "priorities, so you start focused.",
+        job_spec={
+            "prompt": (
+                "Give the user a brief weekday start-of-day nudge: their "
+                "calendar for today and the 1-3 highest-priority things to "
+                "focus on, inferred from recent context and any task tools. "
+                "Encouraging, short, one message."
+            ),
+            "schedule": "0 9 * * 1-5",
+            "name": "Workday start reminder",
+            "deliver": "origin",
+        },
+    ),
+]
+
+
+def seed_catalog_suggestions(
+    *,
+    add_fn: Optional[Callable[..., Optional[Dict[str, Any]]]] = None,
+    keys: Optional[List[str]] = None,
+) -> List[Dict[str, Any]]:
+    """Register catalog entries as pending suggestions.
+
+    ``add_fn`` defaults to ``cron.suggestions.add_suggestion`` (injectable for
+    tests). ``keys`` restricts to specific catalog entries; omit to seed all.
+    Entries already dismissed/accepted (by dedup key) or beyond the pending cap
+    are skipped by the store, so re-seeding is safe and idempotent. Returns the
+    list of suggestion records actually created.
+    """
+    if add_fn is None:
+        from cron.suggestions import add_suggestion as add_fn  # type: ignore[assignment]
+
+    wanted = set(keys) if keys else None
+    created: List[Dict[str, Any]] = []
+    for entry in CATALOG:
+        if wanted is not None and entry.key not in wanted:
+            continue
+        rec = add_fn(
+            title=entry.title,
+            description=entry.description,
+            source="catalog",
+            job_spec=dict(entry.job_spec),
+            dedup_key=entry.key,
+        )
+        if rec is not None:
+            created.append(rec)
+    return created