@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/autonomous.py

@@ -0,0 +1,538 @@
+"""Autonomous-agent supervisor — first-class persistent nodes of the engine.
+
+An autonomous agent is a `Task` with `lifecycle: persistent` and a `Trigger`.
+Charters live as YAML files in `Agentik_Orchestration/autonomous/`. The
+supervisor loads every charter, schedules each agent, and — when a trigger
+fires — opens a mission via the same `run_mission()` pipeline the rest of the
+engine uses. The autonomous agent inherits verified completion and the deadman
+for free; it is *our* architecture, configured.
+
+Four trigger types are honoured:
+
+  * ``cron``    -- a 5-field schedule (`m h d M w`). Numeric, ``*``, ``*/N``,
+                   comma lists. The supervisor's main loop polls due agents.
+  * ``event``   -- subscribed to the event bus; fires when an event matches the
+                   configured ``event_type`` pattern.
+  * ``webhook`` -- the supervisor exposes :meth:`wake_webhook` — an external
+                   HTTP shim invokes it when a request arrives at the agent's
+                   webhook_path.
+  * ``channel`` -- the Telegram daemon calls :meth:`on_channel_message` for
+                   messages on the agent's bound topic.
+
+The supervisor is deliberately stdlib-only: it can run on a fresh VPS with no
+extra Python deps beyond pyyaml (already an engine dep).
+"""
+from __future__ import annotations
+
+import logging
+import os
+import signal
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+import yaml
+
+from omega_engine.events import Event
+from omega_engine.task import Lifecycle
+
+logger = logging.getLogger("omega.autonomous")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Charter
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class Charter:
+    """A persistent agent's contract — one YAML file = one charter.
+
+    The dataclass mirrors the fields documented in
+    ``docs/AUTONOMOUS-AGENTS.md`` §3. Missing optional fields fall back to the
+    same defaults the example charters use.
+    """
+
+    id: str
+    role: str
+    trigger_type: str                  # "cron" | "event" | "webhook" | "channel"
+    trigger_config: dict[str, Any] = field(default_factory=dict)
+    charter: str = ""
+    lifecycle: str = Lifecycle.PERSISTENT.value
+    channel_topic: Optional[int] = None
+    max_iterations: int = 5
+    heartbeat_interval_s: int = 300
+    provider: Optional[str] = None
+    allowed_skills: list[str] = field(default_factory=list)
+    allowed_mcp: list[str] = field(default_factory=list)
+    allowed_topologies: list[str] = field(default_factory=list)
+    may_spawn_missions: bool = True
+    may_ship: bool = False
+    source_file: Optional[str] = None  # filled by load_charters for diagnostics
+
+
+def _is_charter_mapping(value: Any) -> bool:
+    """A YAML top-level mapping is a charter iff it has id + role + trigger.
+
+    This is what lets a single file hold both worked examples and the template
+    block (which lacks an ``id``/``role`` — the template is a placeholder, not
+    a charter).
+    """
+    if not isinstance(value, dict):
+        return False
+    if not value.get("id") or not value.get("role"):
+        return False
+    trig = value.get("trigger")
+    if not isinstance(trig, dict) or not trig.get("type"):
+        return False
+    return True
+
+
+def _charter_from_mapping(data: dict[str, Any], *,
+                          source_file: str | None = None) -> Charter:
+    trig = data.get("trigger") or {}
+    chan = data.get("channel") or {}
+    budget = data.get("budget") or {}
+    allowed = data.get("allowed") or {}
+    guard = data.get("guardrails") or {}
+    return Charter(
+        id=str(data["id"]),
+        role=str(data["role"]),
+        trigger_type=str(trig.get("type", "")),
+        trigger_config=dict(trig.get("config") or {}),
+        charter=str(data.get("charter", "")).strip(),
+        lifecycle=str(data.get("lifecycle", Lifecycle.PERSISTENT.value)),
+        channel_topic=chan.get("telegram_topic"),
+        max_iterations=int(budget.get("max_iterations", 5)),
+        heartbeat_interval_s=int(budget.get("heartbeat_interval_s", 300)),
+        provider=data.get("provider"),
+        allowed_skills=list(allowed.get("skills") or []),
+        allowed_mcp=list(allowed.get("mcp") or []),
+        allowed_topologies=list(allowed.get("topologies") or []),
+        may_spawn_missions=bool(guard.get("may_spawn_missions", True)),
+        may_ship=bool(guard.get("may_ship", False)),
+        source_file=source_file,
+    )
+
+
+def load_charters(directory: str | Path) -> list[Charter]:
+    """Load every charter under ``directory`` — recursively scans ``*.yaml``.
+
+    A YAML file may hold ONE charter at top level OR a mapping-of-mappings where
+    each value is a charter (the example file uses the second form). Entries
+    that do not look like a charter (e.g. the ``template:`` placeholder block in
+    the example) are silently skipped — they're documentation, not agents.
+    """
+    base = Path(directory)
+    out: list[Charter] = []
+    if not base.is_dir():
+        return out
+
+    for path in sorted(base.rglob("*.yaml")):
+        try:
+            data = yaml.safe_load(path.read_text()) or {}
+        except yaml.YAMLError as exc:
+            logger.warning("autonomous: cannot parse %s: %s", path, exc)
+            continue
+
+        if not isinstance(data, dict):
+            continue
+
+        # case 1: the whole file IS a single charter
+        if _is_charter_mapping(data):
+            out.append(_charter_from_mapping(data, source_file=str(path)))
+            continue
+
+        # case 2: mapping of named charters (the example file). Each value that
+        # looks like a charter is loaded; everything else (template, comments)
+        # is skipped.
+        for key, value in data.items():
+            if key == "template":
+                # the template block is explicitly documentation
+                continue
+            if _is_charter_mapping(value):
+                out.append(_charter_from_mapping(value, source_file=str(path)))
+
+    return out
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Minimal cron parser
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Field order: minute hour day-of-month month day-of-week
+# Ranges: m=0-59 h=0-23 dom=1-31 mo=1-12 dow=0-6 (Sun=0)
+_FIELD_RANGES: list[tuple[int, int]] = [
+    (0, 59), (0, 23), (1, 31), (1, 12), (0, 6),
+]
+
+
+def _parse_field(spec: str, lo: int, hi: int) -> set[int]:
+    """Parse one cron field into the set of integers it matches.
+
+    Supported forms (covers every form used by the example charters):
+        *
+        N
+        a,b,c
+        */N
+        a-b  (range — same syntax as standard cron)
+    """
+    spec = spec.strip()
+    if spec == "*":
+        return set(range(lo, hi + 1))
+
+    if spec.startswith("*/"):
+        step = int(spec[2:])
+        if step <= 0:
+            raise ValueError(f"step must be positive: {spec}")
+        return {n for n in range(lo, hi + 1) if (n - lo) % step == 0}
+
+    out: set[int] = set()
+    for piece in spec.split(","):
+        piece = piece.strip()
+        if "-" in piece:
+            a, b = piece.split("-", 1)
+            ai, bi = int(a), int(b)
+            if ai > bi or ai < lo or bi > hi:
+                raise ValueError(f"bad range {piece} for field [{lo},{hi}]")
+            out.update(range(ai, bi + 1))
+        else:
+            n = int(piece)
+            if n < lo or n > hi:
+                raise ValueError(f"value {n} outside [{lo},{hi}]")
+            out.add(n)
+    return out
+
+
+def parse_cron(spec: str) -> tuple[set[int], ...]:
+    """Parse a 5-field cron spec into 5 sets — one per field."""
+    parts = spec.split()
+    if len(parts) != 5:
+        raise ValueError(
+            f"cron spec must have 5 fields, got {len(parts)}: {spec!r}"
+        )
+    return tuple(
+        _parse_field(parts[i], *_FIELD_RANGES[i]) for i in range(5)
+    )
+
+
+def next_fire(spec: str, now: float) -> float:
+    """Return the next epoch second at or after ``now`` when ``spec`` fires.
+
+    Naive but correct: walk forward minute-by-minute. The example charters fire
+    at most a handful of times a day; the search is always bounded by the
+    longest legal gap (year + 1 day for safety). For the spec ``*/5 * * * *``
+    this returns now+~5min.
+    """
+    minute, hour, dom, month, dow = parse_cron(spec)
+    # round up to next minute boundary
+    t = time.localtime(now)
+    candidate = time.mktime((
+        t.tm_year, t.tm_mon, t.tm_mday, t.tm_hour, t.tm_min, 0,
+        0, 0, -1,
+    )) + 60  # next minute (drop seconds)
+
+    # 5 years bounded search — way past any reasonable schedule
+    cutoff = candidate + 366 * 24 * 60 * 60 * 5
+    while candidate < cutoff:
+        ct = time.localtime(candidate)
+        # cron weekday: Sun=0..Sat=6; struct_tm tm_wday: Mon=0..Sun=6
+        c_dow = (ct.tm_wday + 1) % 7
+        if (ct.tm_min in minute
+                and ct.tm_hour in hour
+                and ct.tm_mday in dom
+                and ct.tm_mon in month
+                and c_dow in dow):
+            return candidate
+        candidate += 60
+    raise RuntimeError(f"no cron fire within 5 years for {spec!r}")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Supervisor
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class _Schedule:
+    """Per-charter scheduler bookkeeping. Only used internally."""
+
+    charter: Charter
+    next_fire_at: Optional[float] = None  # cron only
+    last_run_at: Optional[float] = None
+    runs: int = 0
+    errors: int = 0
+    last_error: Optional[str] = None
+
+
+# default runner type — what fires when a trigger trips
+MissionRunner = Callable[..., Any]
+
+
+def _default_runner(*, intent: str,
+                    omega_home: str | Path | None,
+                    topic_id: int | None,
+                    telegram: Any | None,
+                    charter: Charter) -> Any:
+    """The production runner — delegates to :func:`run_mission` lazily.
+
+    Imported lazily so unit tests can build a supervisor without dragging the
+    full executor stack into the test fixture.
+    """
+    from omega_engine.mission import run_mission
+
+    return run_mission(
+        intent=intent,
+        omega_home=omega_home,
+        topic_id=topic_id,
+        telegram=telegram,
+    )
+
+
+class AutonomousSupervisor:
+    """Loads charters, schedules them, runs forever.
+
+    The supervisor is deliberately single-threaded: it polls its schedule on a
+    tick, dispatches due missions synchronously, and surfaces any per-charter
+    failure as a logged error — never as a process exit. One bad charter cannot
+    take the whole supervisor down.
+    """
+
+    def __init__(
+        self,
+        charters: list[Charter],
+        *,
+        omega_home: str | Path | None = None,
+        telegram: Any | None = None,
+        bus: Any | None = None,
+        runner: MissionRunner | None = None,
+        tick_seconds: float = 5.0,
+    ) -> None:
+        self._omega_home = omega_home
+        self._telegram = telegram
+        self._bus = bus
+        self._runner: MissionRunner = runner or _default_runner
+        self._tick = max(0.5, float(tick_seconds))
+        self._schedules: dict[str, _Schedule] = {
+            c.id: _Schedule(c) for c in charters
+        }
+        self._stop = threading.Event()
+        self._lock = threading.Lock()
+        # event-triggered agents register a bus subscription on .run()
+        # webhook + channel triggers are awakened by external callers
+        self._init_cron_schedules()
+        if bus is not None:
+            self._wire_event_subscribers()
+
+    # -- public surface ------------------------------------------------------
+
+    def charters(self) -> list[Charter]:
+        with self._lock:
+            return [s.charter for s in self._schedules.values()]
+
+    def stats(self) -> dict[str, dict[str, Any]]:
+        """For ``omega status`` / diagnostics."""
+        with self._lock:
+            return {
+                cid: {
+                    "trigger": s.charter.trigger_type,
+                    "next_fire_at": s.next_fire_at,
+                    "last_run_at": s.last_run_at,
+                    "runs": s.runs,
+                    "errors": s.errors,
+                    "last_error": s.last_error,
+                }
+                for cid, s in self._schedules.items()
+            }
+
+    def stop(self) -> None:
+        """Request a graceful shutdown. ``run()`` returns on the next tick."""
+        self._stop.set()
+
+    def run(self) -> None:
+        """Main loop. Returns only when :meth:`stop` is called or SIGTERM/SIGINT
+        is received. Crashes inside a single charter never escape this loop."""
+        # one-time SIGTERM/SIGINT wiring — only if we're on the main thread
+        # (so the daemon CLI installs them; tests can drive run() differently).
+        try:
+            signal.signal(signal.SIGTERM, lambda *_: self.stop())
+            signal.signal(signal.SIGINT, lambda *_: self.stop())
+        except ValueError:
+            # not on the main thread — caller handles signals
+            pass
+
+        logger.info("autonomous supervisor: %d charter(s) active",
+                    len(self._schedules))
+        while not self._stop.is_set():
+            self._tick_once()
+            self._stop.wait(self._tick)
+        logger.info("autonomous supervisor: stopping cleanly")
+
+    # explicit single-tick variant — used by tests to step the loop
+    def tick(self, now: float | None = None) -> list[str]:
+        """Run one schedule pass; return the charter ids that fired this tick."""
+        return self._tick_once(now=now)
+
+    # -- trigger entry points ------------------------------------------------
+
+    def on_channel_message(self, topic_id: int, text: str) -> list[str]:
+        """Wake every charter bound to ``topic_id`` (channel trigger).
+
+        The Telegram daemon calls this for every inbound message it sees. The
+        text becomes the mission intent — the charter's role + channel binding
+        is what makes it an autonomous-agent action and not a one-shot call.
+        """
+        fired: list[str] = []
+        for sched in self._schedules.values():
+            c = sched.charter
+            if c.trigger_type != "channel":
+                continue
+            cfg_topic = c.trigger_config.get("telegram_topic", c.channel_topic)
+            if cfg_topic is None or int(cfg_topic) != int(topic_id):
+                continue
+            self._fire(sched, intent=text)
+            fired.append(c.id)
+        return fired
+
+    def wake_webhook(self, path: str, payload: dict[str, Any] | None = None
+                     ) -> list[str]:
+        """Wake every charter whose webhook trigger matches ``path``.
+
+        The supervisor does NOT itself bind a port — an external HTTP shim is
+        responsible for that. The shim calls this method on a hit; one charter
+        ↔ one path (matched on ``webhook_path`` in its trigger config).
+        """
+        payload = payload or {}
+        fired: list[str] = []
+        for sched in self._schedules.values():
+            c = sched.charter
+            if c.trigger_type != "webhook":
+                continue
+            wp = c.trigger_config.get("webhook_path")
+            if not wp or wp != path:
+                continue
+            intent = payload.get("intent") or f"{c.role}: webhook fired ({path})"
+            self._fire(sched, intent=intent, extra_context={"payload": payload})
+            fired.append(c.id)
+        return fired
+
+    # -- internals -----------------------------------------------------------
+
+    def _init_cron_schedules(self) -> None:
+        now = time.time()
+        for sched in self._schedules.values():
+            if sched.charter.trigger_type != "cron":
+                continue
+            spec = sched.charter.trigger_config.get("schedule")
+            if not spec:
+                logger.warning("autonomous: charter %s has cron trigger but no "
+                               "schedule — skipping", sched.charter.id)
+                continue
+            try:
+                sched.next_fire_at = next_fire(spec, now)
+            except (ValueError, RuntimeError) as exc:
+                sched.last_error = f"cron parse: {exc}"
+                sched.errors += 1
+                logger.warning("autonomous: charter %s has bad cron %r: %s",
+                               sched.charter.id, spec, exc)
+
+    def _wire_event_subscribers(self) -> None:
+        """Hook the engine's event bus for charters with an event trigger."""
+        for sched in self._schedules.values():
+            c = sched.charter
+            if c.trigger_type != "event":
+                continue
+            pattern = c.trigger_config.get("event_type", "")
+            if not pattern:
+                continue
+            self._bus.subscribe(self._make_event_handler(sched, pattern))
+
+    def _make_event_handler(self, sched: _Schedule, pattern: str
+                            ) -> Callable[[Event], None]:
+        def handler(event: Event) -> None:
+            etype = event.type.value if hasattr(event.type, "value") else str(event.type)
+            # support exact match and a trailing wildcard (``task.*``)
+            if pattern.endswith("*"):
+                if not etype.startswith(pattern[:-1]):
+                    return
+            elif etype != pattern:
+                return
+            intent = f"{sched.charter.role}: event {etype} on {event.task_id}"
+            self._fire(sched, intent=intent,
+                       extra_context={"event_task_id": event.task_id,
+                                      "event_type": etype,
+                                      "event_payload": event.payload})
+        return handler
+
+    def _tick_once(self, now: float | None = None) -> list[str]:
+        now = now if now is not None else time.time()
+        fired: list[str] = []
+        with self._lock:
+            scheds = list(self._schedules.values())
+        for sched in scheds:
+            if sched.charter.trigger_type != "cron":
+                continue
+            if sched.next_fire_at is None:
+                continue
+            if now >= sched.next_fire_at:
+                spec = sched.charter.trigger_config.get("schedule", "")
+                intent = (f"{sched.charter.role}: cron tick "
+                          f"({spec}) — {time.strftime('%Y-%m-%d %H:%M')}")
+                self._fire(sched, intent=intent,
+                           extra_context={"cron_schedule": spec, "fired_at": now})
+                fired.append(sched.charter.id)
+                # reschedule for next fire
+                try:
+                    sched.next_fire_at = next_fire(spec, now + 60)
+                except (ValueError, RuntimeError) as exc:
+                    sched.last_error = f"reschedule: {exc}"
+                    sched.errors += 1
+                    sched.next_fire_at = None
+        return fired
+
+    def _fire(self, sched: _Schedule, *, intent: str,
+              extra_context: dict[str, Any] | None = None) -> None:
+        """Invoke the runner once; absorb every exception per charter."""
+        c = sched.charter
+        sched.runs += 1
+        sched.last_run_at = time.time()
+        logger.info("autonomous: firing %s (%s) — intent=%r",
+                    c.id, c.trigger_type, intent[:120])
+        try:
+            self._runner(
+                intent=intent,
+                omega_home=self._omega_home,
+                topic_id=c.channel_topic,
+                telegram=self._telegram,
+                charter=c,
+            )
+        except Exception as exc:  # noqa: BLE001 — never let one bad charter kill us
+            sched.errors += 1
+            sched.last_error = f"{type(exc).__name__}: {exc}"
+            logger.exception("autonomous: charter %s crashed during fire", c.id)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Convenience — build a supervisor straight from OMEGA_HOME
+# ─────────────────────────────────────────────────────────────────────────────
+
+def build_supervisor_from_home(
+    omega_home: str | Path | None = None,
+    *,
+    telegram: Any | None = None,
+    bus: Any | None = None,
+    runner: MissionRunner | None = None,
+) -> AutonomousSupervisor:
+    """Discover charters in ``$OMEGA_HOME/Agentik_Orchestration/autonomous/`` and
+    return a ready-to-run supervisor."""
+    home = Path(omega_home or os.environ.get(
+        "OMEGA_HOME", str(Path.home() / "Omega")))
+    charter_dir = home / "Agentik_Orchestration" / "autonomous"
+    charters = load_charters(charter_dir)
+    return AutonomousSupervisor(
+        charters,
+        omega_home=home,
+        telegram=telegram,
+        bus=bus,
+        runner=runner,
+    )