polyrob 0.5.0__py3-none-any.whl

cron/jobs.py

@@ -0,0 +1,207 @@
+"""SQLite-backed cron job store (roadmap P5).
+
+A single ``cron_jobs`` table holding durable schedule state. Uses WAL mode with a
+jittered retry on write contention (mirrors Reference ``SessionDB`` and foreshadows
+the P6 session-registry migration). The store is intentionally schedule-agnostic:
+callers compute ``next_run_at`` with :mod:`cron.schedule` and hand it in.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from core.sqlite_util import execute_retry
+
+
+@dataclass
+class CronJob:
+    id: str
+    task: str
+    schedule_spec: str
+    user_id: str
+    next_run_at: Optional[datetime]
+    one_shot: bool = False
+    # DORMANT (ME-D2): never consumed by the runner; retained to avoid a schema
+    # migration. Wire or drop in a dedicated proposal. Not settable via
+    # CronService.schedule — always takes this default.
+    skip_memory: bool = True
+    max_duration_seconds: int = 180
+    payload: Dict[str, Any] = field(default_factory=dict)
+    enabled: bool = True
+    status: str = "scheduled"  # scheduled|running|done|failed|cancelled
+    last_run_at: Optional[datetime] = None
+    created_at: Optional[datetime] = None
+
+
+def _iso(dt: Optional[datetime]) -> Optional[str]:
+    return dt.isoformat() if dt else None
+
+
+def _parse(s: Optional[str]) -> Optional[datetime]:
+    return datetime.fromisoformat(s) if s else None
+
+
+class CronJobStore:
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        parent = os.path.dirname(db_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        self._init_schema()
+        # NOTE: crash-orphaned 'running' jobs are reclaimed by the scheduler at the
+        # start of each tick *under the held TickLock* (see CronScheduler._run_due),
+        # NOT here. Calling reclaim in __init__ ran without the lock, so a second
+        # CronJobStore built mid-tick (e.g. by the agent-facing CronJobTool, or
+        # another worker's lifespan under UVICORN_WORKERS>1) would reset a genuinely
+        # live job back to 'scheduled' and cause it to run twice.
+
+    def _init_schema(self) -> None:
+        execute_retry(
+            self.db_path,
+            """
+            CREATE TABLE IF NOT EXISTS cron_jobs (
+                id TEXT PRIMARY KEY,
+                task TEXT NOT NULL,
+                schedule_spec TEXT NOT NULL,
+                user_id TEXT NOT NULL,
+                next_run_at TEXT,
+                one_shot INTEGER NOT NULL DEFAULT 0,
+                -- DORMANT (ME-D2): never consumed by the runner; retained to avoid
+                -- a schema migration. Wire or drop in a dedicated proposal.
+                skip_memory INTEGER NOT NULL DEFAULT 1,
+                max_duration_seconds INTEGER NOT NULL DEFAULT 180,
+                payload TEXT NOT NULL DEFAULT '{}',
+                enabled INTEGER NOT NULL DEFAULT 1,
+                status TEXT NOT NULL DEFAULT 'scheduled',
+                last_run_at TEXT,
+                created_at TEXT NOT NULL
+            )
+            """
+        )
+
+    # --- row mapping ---------------------------------------------------------
+
+    @staticmethod
+    def _row_to_job(row: sqlite3.Row) -> CronJob:
+        return CronJob(
+            id=row["id"], task=row["task"], schedule_spec=row["schedule_spec"],
+            user_id=row["user_id"], next_run_at=_parse(row["next_run_at"]),
+            one_shot=bool(row["one_shot"]), skip_memory=bool(row["skip_memory"]),
+            max_duration_seconds=row["max_duration_seconds"],
+            payload=json.loads(row["payload"] or "{}"),
+            enabled=bool(row["enabled"]), status=row["status"],
+            last_run_at=_parse(row["last_run_at"]), created_at=_parse(row["created_at"]),
+        )
+
+    # --- CRUD ----------------------------------------------------------------
+
+    def add(self, job: CronJob) -> CronJob:
+        created = job.created_at or datetime(2026, 1, 1)  # caller may override
+        execute_retry(
+            self.db_path,
+            """
+            INSERT INTO cron_jobs (id, task, schedule_spec, user_id, next_run_at,
+                one_shot, skip_memory, max_duration_seconds, payload, enabled, status,
+                last_run_at, created_at)
+            VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)
+            """,
+            (
+                job.id, job.task, job.schedule_spec, job.user_id, _iso(job.next_run_at),
+                int(job.one_shot), int(job.skip_memory), job.max_duration_seconds,
+                json.dumps(job.payload), int(job.enabled), job.status,
+                _iso(job.last_run_at), _iso(created),
+            ),
+        )
+        job.created_at = created
+        return job
+
+    def get(self, job_id: str, *, user_id: Optional[str] = None) -> Optional[CronJob]:
+        sql = "SELECT * FROM cron_jobs WHERE id=?"
+        params: tuple = (job_id,)
+        if user_id is not None:
+            sql += " AND user_id=?"
+            params = (job_id, user_id)
+        row = execute_retry(self.db_path, sql, params, fetch="one")
+        return self._row_to_job(row) if row else None
+
+    def list(self, user_id: Optional[str] = None, enabled_only: bool = False) -> List[CronJob]:
+        sql = "SELECT * FROM cron_jobs"
+        clauses, params = [], []
+        if user_id is not None:
+            clauses.append("user_id=?")
+            params.append(user_id)
+        if enabled_only:
+            clauses.append("enabled=1")
+        if clauses:
+            sql += " WHERE " + " AND ".join(clauses)
+        sql += " ORDER BY created_at"
+        rows = execute_retry(self.db_path, sql, tuple(params), fetch="all")
+        return [self._row_to_job(r) for r in rows]
+
+    def due(self, now: datetime) -> List[CronJob]:
+        rows = execute_retry(
+            self.db_path,
+            """
+            SELECT * FROM cron_jobs
+            WHERE enabled=1 AND status IN ('scheduled')
+              AND next_run_at IS NOT NULL AND next_run_at <= ?
+            ORDER BY next_run_at
+            """,
+            (_iso(now),), fetch="all",
+        )
+        return [self._row_to_job(r) for r in rows]
+
+    def update_after_run(self, job_id: str, *, last_run_at: datetime,
+                         next_run_at: Optional[datetime], status: str) -> None:
+        execute_retry(
+            self.db_path,
+            "UPDATE cron_jobs SET last_run_at=?, next_run_at=?, status=? WHERE id=?",
+            (_iso(last_run_at), _iso(next_run_at), status, job_id),
+        )
+
+    def set_status(self, job_id: str, status: str) -> None:
+        execute_retry(self.db_path, "UPDATE cron_jobs SET status=? WHERE id=?", (status, job_id))
+
+    def claim_for_run(self, job_id: str) -> bool:
+        """Atomically transition a job 'scheduled' -> 'running'.
+
+        Returns True iff THIS caller won the claim (rowcount == 1). A compare-and-set
+        on status='scheduled' so two ticks can never both run the same job — the
+        non-CAS set_status('running') it replaces could double-run a job if a tick
+        ever raced a reclaim.
+        """
+        rowcount = execute_retry(
+            self.db_path,
+            "UPDATE cron_jobs SET status='running' WHERE id=? AND status='scheduled'",
+            (job_id,),
+        )
+        return bool(rowcount)
+
+    def reclaim_stale_running(self) -> int:
+        """Reset jobs stuck in 'running' (process died mid-run) back to 'scheduled'.
+
+        Returns the number of rows reclaimed. MUST be called only under the held cron
+        TickLock (the scheduler does this at the start of each tick). Ticks are
+        serialized by the lock and always write a terminal/rescheduled status after a
+        run, so any 'running' row observed under the lock is genuinely orphaned by a
+        crash and safe to reclaim. Calling it WITHOUT the lock (e.g. from __init__)
+        could reset a live job and cause a double-run.
+        """
+        return execute_retry(
+            self.db_path,
+            "UPDATE cron_jobs SET status='scheduled' WHERE status='running' AND enabled=1",
+            (),
+        ) or 0
+
+    def cancel(self, job_id: str, *, user_id: Optional[str] = None) -> bool:
+        sql = "UPDATE cron_jobs SET enabled=0, status='cancelled' WHERE id=?"
+        params: tuple = (job_id,)
+        if user_id is not None:
+            sql += " AND user_id=?"
+            params = (job_id, user_id)
+        rowcount = execute_retry(self.db_path, sql, params)
+        return bool(rowcount)

cron/runner.py

@@ -0,0 +1,297 @@
+"""Cron runner + ticker (roadmap P5).
+
+Two pieces:
+
+- :class:`CronTicker` — drives ``scheduler.tick()`` on an interval. Unit-tested
+  via an injected scheduler; the only background-loop concern is here.
+- :func:`make_agent_runner` — the LIVE integration point that turns a ``CronJob``
+  into an agent session on the existing task-agent core, with the per-run cap. This
+  path needs a live agent run to verify (the scheduler's
+  unit tests use a fake runner), so it is opt-in via ``CRON_ENABLED`` and is not
+  wired into the default app lifecycle.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from datetime import datetime
+from typing import Any, Awaitable, Callable, Optional
+
+
+def default_cron_tools() -> list:
+    """Posture-aware default cron toolset (WS-8). Posture 0: ['filesystem','task']
+    (byte-identical). Posture>=1: + the compute tools so a scheduled build/self-env
+    run isn't tool-starved. Mirrors ``goals.dispatcher.default_goal_tools``; resolved
+    at call time so posture 0 is unchanged."""
+    try:
+        from agents.task.goals.dispatcher import default_goal_tools
+        return default_goal_tools()
+    except Exception:
+        return ["filesystem", "task"]
+
+
+def _cron_ev(job, outcome: str, reason: Optional[str] = None, **extra) -> None:
+    """Emit a cron_run event to the durable event log (fail-open). Makes cron
+    lifecycle queryable in the uniform autonomy/governance stream, not just the
+    episodes table (telemetry audit 2026-07-04)."""
+    try:
+        from agents.task.telemetry.event_log import get_event_log, event_log_enabled
+        if event_log_enabled():
+            get_event_log().record(
+                "cron_run", user_id=getattr(job, "user_id", ""),
+                source="cron", job_id=getattr(job, "id", None),
+                outcome=outcome, reason=reason, **extra)
+    except Exception:
+        pass
+
+from agents.task.runtime.run_as_session import run_task_as_session as _run_task_as_session
+from cron.jobs import CronJob
+
+logger = logging.getLogger(__name__)
+
+
+def _cron_tick_is_active(result: Any) -> bool:
+    """A cron tick counts as 'active' (reset the idle-backoff interval to base)
+    when something actually ran or failed. A tick that was merely skipped (lock
+    contention, REPL busy) or found nothing due counts as idle. Named + module-level
+    so it's directly unit-testable without going through the async ticker loop.
+    """
+    return bool(getattr(result, "ran", None)) or bool(getattr(result, "failed", None))
+
+
+class CronTicker:
+    """Periodically fire a scheduler tick until stopped."""
+
+    def __init__(self, scheduler: Any, interval_seconds: int = 60):
+        self.scheduler = scheduler
+        self.interval_seconds = interval_seconds
+
+    async def tick_once(self, now: Optional[datetime] = None):
+        return await self.scheduler.tick(now=now)
+
+    async def run_forever(self, stop_event: Optional[asyncio.Event] = None) -> None:
+        from core.tickers import IntervalTicker
+        from agents.task.constants import (
+            ticker_idle_backoff_enabled,
+            ticker_idle_backoff_max_multiplier,
+        )
+
+        is_active = None
+        max_interval = None
+        if ticker_idle_backoff_enabled():
+            is_active = _cron_tick_is_active
+            max_interval = self.interval_seconds * ticker_idle_backoff_max_multiplier()
+
+        await IntervalTicker(
+            self.scheduler.tick,
+            self.interval_seconds,
+            is_active=is_active,
+            max_interval_seconds=max_interval,
+        ).run_forever(stop_event=stop_event)
+
+
+def make_agent_runner(task_agent: Any, *, data_dir: str = "data") -> Callable[[CronJob], Awaitable[bool]]:
+    """Build a runner that executes a CronJob as an isolated agent session.
+
+    LIVE PATH — reuses ``task_agent.create_session``. A cron run gets cross-session
+    memory recall like any other session; recall is tenant-scoped, so this is not
+    cross-USER contamination. Returns an async ``runner(job) -> bool`` suitable for
+    :class:`cron.scheduler.CronScheduler`. The scheduler already enforces
+    ``job.max_duration_seconds`` as a hard cap.
+    """
+    async def runner(job: CronJob) -> bool:
+        payload = dict(job.payload or {})
+        # Owner daily digest: a deterministic $0 tick composed from evidence and
+        # pushed via the delivery rail — never invokes the model. Routed here
+        # BEFORE the wake/change gates. Fail-open (a compose/deliver error is a
+        # $0 no-op, not a job failure) so a persistent hiccup can't spin.
+        if payload.get("digest"):
+            try:
+                from agents.task.constants import AutonomyConfig
+                if not AutonomyConfig.owner_digest_enabled():
+                    _cron_ev(job, "skipped", "digest_disabled")
+                    return True
+                from cron.digest import run_digest
+                ok = await run_digest(task_agent, job)
+                _cron_ev(job, "done" if ok else "skipped", "digest")
+            except Exception:
+                logger.warning("cron job %s: digest tick failed", job.id, exc_info=True)
+            return True
+        if not payload.get("wake_agent", True):
+            logger.info("cron job %s: wake_agent=False — $0 tick, agent not invoked", job.id)
+            _cron_ev(job, "skipped", "wake_agent_false")
+            return True
+        # Wake change-gate: a change-gated review tick whose state fingerprint is
+        # unchanged since the last SUCCESSFUL run is a $0 tick — same shape as
+        # wake_agent=False. Fail-open (any gate error runs the tick); delivery
+        # jobs are never gated. The outcome-tagged baseline is recorded AFTER the
+        # run (finally below): a failed run never establishes a skippable
+        # baseline, so a persistently-failing job always retries.
+        _gate_active = False
+        try:
+            from cron.wake_gate import gate_applies, should_skip_wake
+            _gate_active = gate_applies(job)
+            if _gate_active and should_skip_wake(job, data_dir=data_dir):
+                logger.info("cron job %s: no observable change — $0 tick, agent not invoked", job.id)
+                _cron_ev(job, "skipped", "no_change")
+                return True
+        except Exception:
+            logger.warning("cron job %s: wake gate error — running tick", job.id, exc_info=True)
+        ok = False
+        try:
+            ok = await _execute(job, payload)
+            return ok
+        finally:
+            if _gate_active:
+                try:
+                    from cron.wake_gate import record_wake_outcome
+                    record_wake_outcome(job, data_dir=data_dir, ok=bool(ok))
+                except Exception:
+                    logger.warning("cron job %s: wake gate outcome record failed", job.id,
+                                   exc_info=True)
+
+    async def _execute(job: CronJob, payload: dict) -> bool:
+        session_id = None
+        _t0 = time.time()
+        _cron_ev(job, "started")
+        from core.runtime_config import resolve_runtime_config
+        provider = payload.get("provider") or resolve_runtime_config(None, None)[0]
+        # Fill the provider's default model from the registry when the job doesn't pin
+        # one — an autonomous run has no interactive config, and a None model crashes
+        # session setup downstream ('.lower()' on None). Mirrors the goal dispatcher.
+        model = payload.get("model")
+        if not model:
+            try:
+                from modules.llm.llm_client_registry import get_default_model
+                model = get_default_model(provider)
+            except Exception:
+                model = None
+        request = {
+            "task": job.task,
+            "provider": provider,
+            "model": model,
+            "tools": payload.get("tools", default_cron_tools()),
+            "max_steps": payload.get("max_steps", 20),
+            "temperature": 0.0,
+            "cron": True,
+        }
+        try:
+            from agents.task.constants import AutonomyConfig
+
+            # Legacy branch (CRON_RUN_LOOP=OFF): create-only, return bool(session_info).
+            # Kept exactly as-is — run_task_as_session does NOT apply here.
+            if not AutonomyConfig.cron_run_loop():
+                session_info = await task_agent.create_session(user_id=job.user_id, request=request)
+                return bool(session_info)
+
+            # W3 LIVE-BUG FIX: route through the shared helper so create_session AND
+            # run_session are both called and refusals are normalised to (sid, None).
+            session_id, final = await _run_task_as_session(
+                task_agent, user_id=job.user_id, request=request, autonomous=True
+            )
+
+            # Back-half: cron-specific log messages + early returns.
+            if session_id is None:
+                logger.error("cron job %s: create_session returned no id", job.id)
+                return False
+            if final is None:
+                # run_task_as_session already collapsed refusal/empty → None; we emit the
+                # original log so operators see one clear refusal line (no double-logging:
+                # run_task_as_session is intentionally silent on refusals).
+                logger.warning("cron job %s: run did not complete (refusal or empty)", job.id)
+                try:
+                    from modules.memory.episodic import finalize_episode
+                    await finalize_episode(
+                        session_id=session_id, user_id=job.user_id, kind="cron",
+                        task=job.task, outcome="failed",
+                        meta={"source": "cron", "job_id": job.id},
+                    )
+                except Exception:
+                    logger.warning("cron episodic write failed", exc_info=True)
+                _cron_ev(job, "failed", "refusal_or_empty", duration_s=round(time.time() - _t0, 3))
+                return False
+
+            # Episodic write happens BEFORE out-of-band delivery (Task 7): delivery's
+            # surfaced-mark is a plain UPDATE keyed on session_id, so the row must
+            # already exist or the mark is a silent no-op. Order matters here.
+            try:
+                from modules.memory.episodic import finalize_episode, collect_provenance
+                orchestrator = task_agent.get_orchestrator(session_id)
+                prov = await collect_provenance(orchestrator)
+                await finalize_episode(
+                    session_id=session_id, user_id=job.user_id, kind="cron",
+                    task=job.task, outcome="done",
+                    summary=str(final)[:2000] if final is not None else None,
+                    spend_usd=prov["spend_usd"], steps=prov["steps"],
+                    artifacts=prov["artifacts"],
+                    meta={"source": "cron", "job_id": job.id},
+                )
+                _cron_ev(job, "done", duration_s=round(time.time() - _t0, 3),
+                         spend_usd=prov.get("spend_usd"), steps=prov.get("steps"))
+            except Exception:
+                logger.warning("cron episodic write failed", exc_info=True)
+
+            # Out-of-band delivery (gated CRON_DELIVERY_ENABLED, default OFF). Runs
+            # inside the scheduler's wait_for budget; fail-open — never fails the job.
+            deliver = payload.get("deliver")
+            if AutonomyConfig.cron_delivery_enabled() and deliver and final:
+                try:
+                    from cron.delivery import deliver_result, delivery_outcome
+                    ok = await deliver_result(
+                        task_agent, job, final,
+                        target=deliver, deliver_target=payload.get("deliver_target"),
+                        session_id=session_id,
+                    )
+                    # Observability: make proactive delivery verifiable in the journal.
+                    # outcome distinguishes a [SILENT] opt-out (suppressed) from a real
+                    # send failure (failed) — they used to both log as ok=False.
+                    logger.info("cron job %s out-of-band delivery target=%s outcome=%s",
+                                job.id, deliver, delivery_outcome(final, ok))
+                except Exception as e:  # belt-and-suspenders; delivery is best-effort
+                    logger.error("cron job %s delivery error: %s", job.id, e, exc_info=True)
+
+            return True
+        except Exception as e:
+            logger.error("cron job %s session failed: %s", job.id, e, exc_info=True)
+            _cron_ev(job, "failed", "exception", duration_s=round(time.time() - _t0, 3),
+                     error=str(e)[:200])
+            if session_id:
+                try:
+                    from modules.memory.episodic import finalize_episode
+                    await finalize_episode(
+                        session_id=session_id, user_id=job.user_id, kind="cron",
+                        task=job.task, outcome="failed", summary=str(e)[:2000],
+                        meta={"source": "cron", "job_id": job.id},
+                    )
+                except Exception:
+                    logger.warning("cron episodic write failed", exc_info=True)
+            return False
+
+    return runner
+
+
+def build_cron_ticker(
+    task_agent: Any,
+    *,
+    data_dir: str = "data",
+    interval_seconds: int = 60,
+) -> CronTicker:
+    """Assemble the full cron stack into a :class:`CronTicker` (B-T1).
+
+    Shares the on-disk job store with the agent-facing ``cronjob`` tool — both use
+    ``<data_dir>/cron.db`` — so jobs scheduled by the tool are picked up by the
+    ticker. The tick lock (``<data_dir>/cron.tick.lock``) keeps a tick safe under
+    ``UVICORN_WORKERS>1``. Opt-in: the FastAPI lifespan only calls this when
+    ``CRON_ENABLED`` is set, so prod is unchanged by default.
+    """
+    from cron.jobs import CronJobStore
+    from cron.scheduler import CronScheduler
+
+    store = CronJobStore(os.path.join(data_dir, "cron.db"))
+    runner = make_agent_runner(task_agent, data_dir=data_dir)
+    scheduler = CronScheduler(
+        store, runner, lock_path=os.path.join(data_dir, "cron.tick.lock")
+    )
+    return CronTicker(scheduler, interval_seconds=interval_seconds)