cascade-orchestrator 0.1.0__py3-none-any.whl

cascade/__init__.py

@@ -0,0 +1,8 @@
+"""Cascade — agent task orchestration platform.
+
+Combines Leantime's strategic coherence (task-goal-milestone links) with
+AgentRQ's agent orchestration (dequeue, status state machine, MCP tools,
+continuous monitoring loop).
+"""
+
+__version__ = "0.1.0"

cascade/config.py

@@ -0,0 +1,48 @@
+"""Application configuration via Pydantic Settings.
+
+All settings can be overridden with environment variables prefixed ``CASCADE_``
+(e.g. ``CASCADE_PORT=8100``) or via a ``.env`` file in the working directory.
+"""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Central configuration for the Cascade platform."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="CASCADE_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # --- Database ---
+    database_url: str = "sqlite+aiosqlite:///./cascade.db"
+
+    # --- Server ---
+    host: str = "0.0.0.0"
+    port: int = 8100
+    reload: bool = True
+
+    # --- Engine ---
+    # Seconds between monitoring-loop ticks. Continuous monitoring, not hourly.
+    loop_tick_seconds: int = 10
+    # Seconds between stall-detection sweeps.
+    stall_check_interval_seconds: int = 300
+    # Minutes of silence before an ongoing task is considered stalled.
+    stall_threshold_minutes: int = 30
+    # Seconds before an agent session with no heartbeat is considered dead.
+    session_timeout_seconds: int = 60
+
+    # --- Scheduling ---
+    scheduler_interval_seconds: int = 60
+
+    # --- Feature flags ---
+    enable_monitoring_loop: bool = True
+    enable_scheduler: bool = True
+
+
+settings = Settings()

cascade/database.py

@@ -0,0 +1,69 @@
+"""Async database engine, session factory and declarative Base.
+
+Provides the single :data:`engine`, the :data:`async_session_factory` and the
+dependency :func:`get_db` used by FastAPI route handlers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+
+from sqlalchemy import event
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+from cascade.config import settings
+
+
+class Base(DeclarativeBase):
+    """Declarative base for all SQLAlchemy 2.0 typed models."""
+
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=False,
+    future=True,
+)
+
+if engine.url.get_backend_name() == "sqlite":
+    # The monitoring loop and API requests hit SQLite from several concurrent
+    # connections. Without WAL + a busy timeout, SQLite's default rollback
+    # journal serialises writers and raises "database is locked" almost
+    # immediately under any real concurrency.
+    @event.listens_for(engine.sync_engine, "connect")
+    def _set_sqlite_pragmas(dbapi_connection, connection_record) -> None:  # noqa: ANN001
+        cursor = dbapi_connection.cursor()
+        cursor.execute("PRAGMA journal_mode=WAL")
+        cursor.execute("PRAGMA busy_timeout=30000")
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.close()
+
+async_session_factory: async_sessionmaker[AsyncSession] = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+    autoflush=False,
+)
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    """FastAPI dependency that yields an :class:`AsyncSession`."""
+    async with async_session_factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def init_db() -> None:
+    """Create all tables. Intended for dev/bootstrap; Alembic is used in prod."""
+    # Importing here ensures every model is registered on ``Base.metadata``.
+    from cascade import models  # noqa: F401  (register models)
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)

cascade/engine/__init__.py

@@ -0,0 +1 @@
+"""Engine: continuous monitoring loop, polling, pinger and progress tracking."""

cascade/engine/loop.py

@@ -0,0 +1,105 @@
+"""Main monitoring loop — continuous execution (10s tick, NOT hourly).
+
+Runs forever (as a background task on app startup) and, on every tick, runs
+the poller, pinger and scheduler concurrently. Stall detection runs on its own
+slower cadence. This is the AgentRQ loop, reimagined as continuous monitoring.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from cascade.config import settings
+from cascade.database import async_session_factory
+from cascade.engine.pinger import pinger_tick
+from cascade.engine.poller import poller_tick
+from cascade.services.scheduler_service import SchedulerService
+
+logger = logging.getLogger(__name__)
+
+# Module-level state so the loop can be stopped gracefully.
+_running = False
+_last_stall_check = 0.0
+
+
+async def scheduler_tick() -> int:
+    """Process due cron templates, returning spawned task count."""
+    async with async_session_factory() as session:
+        svc = SchedulerService(session)
+        spawned = await svc.process_cron_templates()
+    if spawned:
+        logger.info("Scheduler spawned %d cron task(s)", len(spawned))
+    return len(spawned)
+
+
+async def stall_detector_tick() -> int:
+    """Run stall detection on its own slower cadence (every 5 min)."""
+    global _last_stall_check
+    now = time.time()
+    if now - _last_stall_check < settings.stall_check_interval_seconds:
+        return 0
+    _last_stall_check = now
+    async with async_session_factory() as session:
+        return await poller_tick(session)
+
+
+async def _poller_tick_isolated() -> int:
+    """Run the poller in its own session (never share one across concurrent ticks)."""
+    async with async_session_factory() as session:
+        result = await poller_tick(session)
+        await session.commit()
+        return result
+
+
+async def _pinger_tick_isolated() -> int:
+    """Run the pinger in its own session (never share one across concurrent ticks)."""
+    async with async_session_factory() as session:
+        result = await pinger_tick(session)
+        await session.commit()
+        return result
+
+
+async def _tick() -> None:
+    """Run one monitoring tick: poller + pinger + scheduler concurrently.
+
+    Each concurrent piece of work gets its own :class:`AsyncSession` —
+    ``AsyncSession`` is not safe for concurrent use by multiple coroutines,
+    so sharing one across ``asyncio.gather`` would corrupt session state.
+    """
+    results = await asyncio.gather(
+        _poller_tick_isolated(),
+        _pinger_tick_isolated(),
+        scheduler_tick(),
+        stall_detector_tick(),
+        return_exceptions=True,
+    )
+    for name, result in zip(
+        ("poller", "pinger", "scheduler", "stall_detector"), results
+    ):
+        if isinstance(result, BaseException):
+            logger.error("Monitoring tick component %r failed: %s", name, result)
+
+
+async def monitoring_loop() -> None:
+    """Main loop that runs forever, monitoring all projects every 10s."""
+    global _running
+    _running = True
+    logger.info("Cascade monitoring loop started (tick=%ss)", settings.loop_tick_seconds)
+    while _running:
+        try:
+            await _tick()
+        except Exception:  # pragma: no cover - never let the loop die
+            logger.exception("Monitoring tick failed")
+        await asyncio.sleep(settings.loop_tick_seconds)
+    logger.info("Cascade monitoring loop stopped")
+
+
+def stop_monitoring_loop() -> None:
+    """Signal the monitoring loop to stop after the current tick."""
+    global _running
+    _running = False
+
+
+__all__ = ["monitoring_loop", "stop_monitoring_loop", "scheduler_tick"]

cascade/engine/pinger.py

@@ -0,0 +1,39 @@
+"""Pinger — session keep-alive + dead-session eviction.
+
+Runs on the monitoring loop to evict agent sessions whose last heartbeat
+exceeds the configured timeout, so the dashboard's "agent alive" indicator
+stays accurate.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from cascade.engine.progress_tracker import tracker
+from cascade.services.monitor_service import MonitorService
+
+logger = logging.getLogger(__name__)
+
+
+async def pinger_tick(session: AsyncSession) -> int:
+    """Evict dead agent sessions and broadcast status changes via SSE.
+
+    Returns the number of sessions evicted.
+    """
+    monitor_svc = MonitorService(session)
+    # Snapshot BEFORE evicting: a project whose last session just died is
+    # removed from ``_sessions`` entirely, so iterating the dict *after*
+    # eviction would silently skip broadcasting its now-offline status.
+    watched_projects = set(monitor_svc._sessions)  # noqa: SLF001
+    evicted = await monitor_svc.evict_dead_sessions()
+    if evicted:
+        logger.info("Evicted %d dead agent session(s)", evicted)
+        # Notify any dashboard subscribers that liveness may have changed.
+        for project_id in watched_projects:
+            alive = await monitor_svc.is_agent_alive(project_id)
+            await tracker.publish(
+                project_id, "agent_status", {"alive": alive, "evicted": evicted}
+            )
+    return evicted

cascade/engine/poller.py

@@ -0,0 +1,38 @@
+"""Poller — work distribution + stall nudging.
+
+In Cascade, agents pull work via ``get_task`` (dequeue). The poller therefore
+focuses on *push* opportunities that a pull-only model misses: detecting
+stalled tasks and nudging them so work never silently stalls.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from cascade.services.monitor_service import MonitorService
+from cascade.services.project_service import ProjectService
+
+logger = logging.getLogger(__name__)
+
+
+async def poller_tick(session: AsyncSession) -> int:
+    """Detect stalled tasks across all projects and nudge them.
+
+    Returns the number of tasks nudged.
+    """
+    project_svc = ProjectService(session)
+    monitor_svc = MonitorService(session)
+    projects = await project_svc.list_projects(status="active")
+
+    nudged = 0
+    for project in projects:
+        stalled = await monitor_svc.get_stalled_tasks(project.id)
+        for task in stalled:
+            await monitor_svc.nudge_stalled_task(task.id)
+            nudged += 1
+            logger.info("Nudged stalled task %s in project %s", task.id, project.id)
+    if nudged:
+        await session.commit()
+    return nudged

cascade/engine/progress_tracker.py

@@ -0,0 +1,63 @@
+"""Real-time progress aggregation + SSE broadcasting broker.
+
+An in-memory pub/sub keyed by project. SSE clients subscribe to a project's
+queue via :meth:`ProgressTracker.subscribe`; services publish events via
+:meth:`ProgressTracker.publish` which fans out to every subscriber.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import defaultdict
+from collections.abc import AsyncGenerator
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ProgressTracker:
+    """In-memory broadcast broker for Server-Sent Events."""
+
+    def __init__(self) -> None:
+        # project_id -> list of asyncio.Queue
+        self._subscribers: dict[str, list[asyncio.Queue[dict[str, Any]]]] = defaultdict(list)
+
+    def subscribe(self, project_id: str) -> asyncio.Queue[dict[str, Any]]:
+        """Register a new subscriber queue for ``project_id``."""
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=256)
+        self._subscribers[project_id].append(queue)
+        logger.debug("SSE subscriber added for project %s", project_id)
+        return queue
+
+    def unsubscribe(self, project_id: str, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        """Remove a previously-registered subscriber queue."""
+        if project_id in self._subscribers:
+            try:
+                self._subscribers[project_id].remove(queue)
+            except ValueError:
+                pass
+            if not self._subscribers[project_id]:
+                del self._subscribers[project_id]
+
+    async def publish(self, project_id: str, event_type: str, data: dict[str, Any]) -> None:
+        """Broadcast an event to all subscribers of ``project_id``."""
+        message = {"event": event_type, "data": {**data, "project_id": project_id}}
+        for queue in list(self._subscribers.get(project_id, [])):
+            try:
+                queue.put_nowait(message)
+            except asyncio.QueueFull:
+                logger.warning("SSE queue full for project %s; dropping event", project_id)
+
+    async def stream(self, project_id: str) -> AsyncGenerator[dict[str, Any], None]:
+        """Yield events for ``project_id`` until the subscriber disconnects."""
+        queue = self.subscribe(project_id)
+        try:
+            while True:
+                yield await queue.get()
+        finally:
+            self.unsubscribe(project_id, queue)
+
+
+# Module-level singleton used across services and routers.
+tracker = ProgressTracker()

cascade/integrations/__init__.py

@@ -0,0 +1,33 @@
+"""Cascade integration layer.
+
+Bridges external systems (notably the Hermes agent) to the Cascade task
+orchestration platform. The async REST client is always importable; the
+monitor daemon is imported lazily so that consumers who only need the client
+do not pay for its heavier runtime setup.
+
+.. code-block:: python
+
+    from cascade.integrations import CascadeClient
+
+    async with CascadeClient("http://localhost:8100") as client:
+        project = await client.create_project(name="Ship feature X")
+"""
+
+from __future__ import annotations
+
+from cascade.integrations.hermes_bridge import (
+    CascadeAPIError,
+    CascadeClient,
+    DotDict,
+)
+
+__all__ = ["CascadeClient", "CascadeAPIError", "DotDict", "MonitorDaemon"]
+
+
+def __getattr__(name: str):
+    """Lazy-load the monitor daemon to keep the client import lightweight."""
+    if name == "MonitorDaemon":
+        from cascade.integrations.monitor_daemon import MonitorDaemon
+
+        return MonitorDaemon
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")