axion-code 1.0.0__py3-none-any.whl

axion/runtime/recovery.py

@@ -0,0 +1,261 @@
+"""Failure recovery recipes with actual retry execution.
+
+Maps to: rust/crates/runtime/src/recovery_recipes.rs
+"""
+
+from __future__ import annotations
+
+import asyncio
+import enum
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class FailureScenario(enum.Enum):
+    TRUST_PROMPT_UNRESOLVED = "trust_prompt_unresolved"
+    PROMPT_MISDELIVERY = "prompt_misdelivery"
+    STALE_BRANCH = "stale_branch"
+    COMPILE_RED_CROSS_CRATE = "compile_red_cross_crate"
+    MCP_HANDSHAKE_FAILURE = "mcp_handshake_failure"
+    PARTIAL_PLUGIN_STARTUP = "partial_plugin_startup"
+    PROVIDER_FAILURE = "provider_failure"
+
+
+class RecoveryStep(enum.Enum):
+    ACCEPT_TRUST_PROMPT = "accept_trust_prompt"
+    REDIRECT_PROMPT_TO_AGENT = "redirect_prompt_to_agent"
+    REBASE_BRANCH = "rebase_branch"
+    CLEAN_BUILD = "clean_build"
+    RETRY_MCP_HANDSHAKE = "retry_mcp_handshake"
+    RESTART_PLUGIN = "restart_plugin"
+    RESTART_WORKER = "restart_worker"
+    ESCALATE_TO_HUMAN = "escalate_to_human"
+    WAIT_AND_RETRY = "wait_and_retry"
+    LOG_AND_CONTINUE = "log_and_continue"
+
+
+class EscalationPolicy(enum.Enum):
+    ALERT_HUMAN = "alert_human"
+    LOG_AND_CONTINUE = "log_and_continue"
+    ABORT = "abort"
+
+
+@dataclass
+class RecoveryRecipe:
+    """A recovery recipe for a specific failure scenario."""
+
+    scenario: FailureScenario
+    steps: list[RecoveryStep]
+    max_attempts: int = 3
+    escalation: EscalationPolicy = EscalationPolicy.ALERT_HUMAN
+    backoff_ms: int = 1000
+    description: str = ""
+
+
+@dataclass
+class RecoveryContext:
+    """Context available to recovery execution."""
+
+    scenario: FailureScenario
+    worker_id: str | None = None
+    plugin_name: str | None = None
+    mcp_server: str | None = None
+    branch: str | None = None
+    error_message: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RecoveryEvent:
+    """Event recorded during recovery execution."""
+
+    step: RecoveryStep
+    attempt: int
+    success: bool
+    message: str = ""
+    timestamp_ms: int = field(default_factory=lambda: int(time.time() * 1000))
+
+
+@dataclass
+class RecoveryResult:
+    """Result of a recovery attempt."""
+
+    success: bool
+    attempts: int = 0
+    message: str = ""
+    events: list[RecoveryEvent] = field(default_factory=list)
+    escalated: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Step executors
+# ---------------------------------------------------------------------------
+
+# Registry of step execution functions
+StepExecutor = Callable[[RecoveryContext], Awaitable[bool]]
+_step_executors: dict[RecoveryStep, StepExecutor] = {}
+
+
+def register_step_executor(step: RecoveryStep, executor: StepExecutor) -> None:
+    """Register an executor for a recovery step."""
+    _step_executors[step] = executor
+
+
+async def _default_step_executor(step: RecoveryStep, context: RecoveryContext) -> bool:
+    """Default executor that logs and returns success for simple steps."""
+    match step:
+        case RecoveryStep.LOG_AND_CONTINUE:
+            logger.info("Recovery: logging and continuing for %s", context.scenario.value)
+            return True
+        case RecoveryStep.WAIT_AND_RETRY:
+            logger.info("Recovery: waiting before retry for %s", context.scenario.value)
+            await asyncio.sleep(1.0)
+            return True
+        case RecoveryStep.ESCALATE_TO_HUMAN:
+            logger.warning(
+                "Recovery: escalating to human for %s: %s",
+                context.scenario.value, context.error_message,
+            )
+            return True  # Escalation "succeeds" — it's been handed off
+        case _:
+            # Check registered executors
+            executor = _step_executors.get(step)
+            if executor:
+                return await executor(context)
+            logger.warning("No executor for recovery step %s, skipping", step.value)
+            return False
+
+
+# ---------------------------------------------------------------------------
+# Recipe registry
+# ---------------------------------------------------------------------------
+
+def recipe_for(scenario: FailureScenario) -> RecoveryRecipe:
+    """Get the recovery recipe for a given failure scenario."""
+    recipes: dict[FailureScenario, RecoveryRecipe] = {
+        FailureScenario.TRUST_PROMPT_UNRESOLVED: RecoveryRecipe(
+            scenario=scenario,
+            steps=[RecoveryStep.ACCEPT_TRUST_PROMPT],
+            max_attempts=1,
+            description="Auto-resolve trust prompt if allowlisted",
+        ),
+        FailureScenario.PROMPT_MISDELIVERY: RecoveryRecipe(
+            scenario=scenario,
+            steps=[RecoveryStep.REDIRECT_PROMPT_TO_AGENT, RecoveryStep.WAIT_AND_RETRY],
+            max_attempts=3,
+            backoff_ms=500,
+            description="Redirect prompt to correct target with retry",
+        ),
+        FailureScenario.STALE_BRANCH: RecoveryRecipe(
+            scenario=scenario,
+            steps=[RecoveryStep.REBASE_BRANCH],
+            max_attempts=2,
+            description="Rebase stale branch from upstream",
+        ),
+        FailureScenario.COMPILE_RED_CROSS_CRATE: RecoveryRecipe(
+            scenario=scenario,
+            steps=[RecoveryStep.CLEAN_BUILD],
+            max_attempts=2,
+            description="Clean build artifacts and rebuild",
+        ),
+        FailureScenario.MCP_HANDSHAKE_FAILURE: RecoveryRecipe(
+            scenario=scenario,
+            steps=[RecoveryStep.RETRY_MCP_HANDSHAKE, RecoveryStep.WAIT_AND_RETRY],
+            max_attempts=3,
+            backoff_ms=2000,
+            description="Retry MCP handshake with backoff",
+        ),
+        FailureScenario.PARTIAL_PLUGIN_STARTUP: RecoveryRecipe(
+            scenario=scenario,
+            steps=[RecoveryStep.RESTART_PLUGIN],
+            max_attempts=2,
+            description="Restart failed plugin",
+        ),
+        FailureScenario.PROVIDER_FAILURE: RecoveryRecipe(
+            scenario=scenario,
+            steps=[RecoveryStep.RESTART_WORKER, RecoveryStep.WAIT_AND_RETRY],
+            max_attempts=3,
+            backoff_ms=5000,
+            escalation=EscalationPolicy.LOG_AND_CONTINUE,
+            description="Restart worker with backoff, log if persistent",
+        ),
+    }
+    return recipes.get(scenario, RecoveryRecipe(
+        scenario=scenario,
+        steps=[RecoveryStep.ESCALATE_TO_HUMAN],
+        max_attempts=1,
+        escalation=EscalationPolicy.ABORT,
+        description="Unknown scenario — escalate immediately",
+    ))
+
+
+# ---------------------------------------------------------------------------
+# Recovery executor
+# ---------------------------------------------------------------------------
+
+async def attempt_recovery(
+    scenario: FailureScenario,
+    context: RecoveryContext | None = None,
+) -> RecoveryResult:
+    """Execute the recovery recipe for a scenario.
+
+    Runs steps in order, retrying up to max_attempts with backoff.
+    Falls back to escalation policy if all attempts fail.
+    """
+    recipe = recipe_for(scenario)
+    ctx = context or RecoveryContext(scenario=scenario)
+    result = RecoveryResult()
+
+    for attempt in range(1, recipe.max_attempts + 1):
+        result.attempts = attempt
+        all_steps_ok = True
+
+        for step in recipe.steps:
+            try:
+                success = await _default_step_executor(step, ctx)
+            except Exception as exc:
+                logger.error("Recovery step %s failed: %s", step.value, exc)
+                success = False
+
+            event = RecoveryEvent(
+                step=step, attempt=attempt, success=success,
+                message=f"Step {step.value}: {'OK' if success else 'FAILED'}",
+            )
+            result.events.append(event)
+
+            if not success:
+                all_steps_ok = False
+                break
+
+        if all_steps_ok:
+            result.success = True
+            result.message = f"Recovered after {attempt} attempt(s)"
+            return result
+
+        # Backoff before retry
+        if attempt < recipe.max_attempts:
+            delay_ms = recipe.backoff_ms * (2 ** (attempt - 1))
+            logger.info("Recovery attempt %d failed, retrying in %dms", attempt, delay_ms)
+            await asyncio.sleep(delay_ms / 1000.0)
+
+    # All attempts exhausted — escalate
+    result.message = f"Recovery failed after {recipe.max_attempts} attempt(s)"
+
+    match recipe.escalation:
+        case EscalationPolicy.ALERT_HUMAN:
+            result.escalated = True
+            result.message += " — escalated to human"
+            logger.warning("Recovery escalated: %s", result.message)
+        case EscalationPolicy.LOG_AND_CONTINUE:
+            result.message += " — logged and continuing"
+            logger.warning("Recovery failed but continuing: %s", result.message)
+        case EscalationPolicy.ABORT:
+            result.escalated = True
+            result.message += " — aborting"
+            logger.error("Recovery failed, aborting: %s", result.message)
+
+    return result

axion/runtime/remote.py

@@ -0,0 +1,28 @@
+"""Remote session support.
+
+Maps to: rust/crates/runtime/src/remote.rs
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class RemoteSessionContext:
+    """Context for a remote session connection."""
+
+    session_id: str
+    host: str
+    port: int = 0
+    protocol: str = "https"
+    auth_token: str | None = None
+
+
+@dataclass
+class UpstreamProxy:
+    """Proxy configuration for upstream connections."""
+
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    timeout_ms: int = 30_000

axion/runtime/sandbox.py

@@ -0,0 +1,68 @@
+"""Sandbox detection and configuration.
+
+Maps to: rust/crates/runtime/src/sandbox.rs
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+from dataclasses import dataclass
+
+
+@dataclass
+class SandboxStatus:
+    """Status of the execution sandbox."""
+
+    available: bool
+    enabled: bool
+    platform: str
+    details: str = ""
+
+
+def detect_sandbox() -> SandboxStatus:
+    """Detect sandbox capabilities on the current platform."""
+    plat = platform.system().lower()
+
+    if plat == "linux":
+        # Check for common sandboxing tools
+        has_firejail = os.path.exists("/usr/bin/firejail")
+        has_bubblewrap = os.path.exists("/usr/bin/bwrap")
+        has_docker = os.path.exists("/usr/bin/docker")
+
+        if has_firejail:
+            return SandboxStatus(
+                available=True, enabled=False, platform="linux",
+                details="firejail available",
+            )
+        if has_bubblewrap:
+            return SandboxStatus(
+                available=True, enabled=False, platform="linux",
+                details="bubblewrap available",
+            )
+        if has_docker:
+            return SandboxStatus(
+                available=True, enabled=False, platform="linux",
+                details="docker available",
+            )
+        return SandboxStatus(
+            available=False, enabled=False, platform="linux",
+            details="No sandbox tools found (install firejail or bubblewrap)",
+        )
+
+    if plat == "darwin":
+        return SandboxStatus(
+            available=True, enabled=False, platform="macos",
+            details="macOS sandbox-exec available",
+        )
+
+    if plat == "windows":
+        return SandboxStatus(
+            available=False, enabled=False, platform="windows",
+            details="Sandboxing not supported on Windows",
+        )
+
+    return SandboxStatus(
+        available=False, enabled=False, platform=plat,
+        details=f"Unknown platform: {plat}",
+    )

axion/runtime/scheduler.py

@@ -0,0 +1,231 @@
+"""Cron scheduler loop — runs scheduled tasks on a timer.
+
+Checks the CronRegistry every minute and triggers due tasks by
+creating entries in the TaskRegistry and optionally spawning workers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Awaitable, Callable
+
+from axion.runtime.tasks import CronRegistry, TaskPacket, TaskRegistry
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Cron expression parser (basic: minute hour day month weekday)
+# ---------------------------------------------------------------------------
+
+def cron_matches_now(expression: str, now: datetime | None = None) -> bool:
+    """Check if a cron expression matches the current (or given) time.
+
+    Supports: * (any), specific values, comma-separated lists, and */N (step).
+    Format: minute hour day_of_month month day_of_week
+    """
+    now = now or datetime.now()
+    parts = expression.strip().split()
+    if len(parts) != 5:
+        logger.warning("Invalid cron expression (need 5 fields): %s", expression)
+        return False
+
+    fields = [
+        (parts[0], now.minute, 0, 59),
+        (parts[1], now.hour, 0, 23),
+        (parts[2], now.day, 1, 31),
+        (parts[3], now.month, 1, 12),
+        (parts[4], now.weekday(), 0, 6),  # 0=Monday in Python
+    ]
+
+    for pattern, current, low, high in fields:
+        if not _field_matches(pattern, current, low, high):
+            return False
+    return True
+
+
+def _field_matches(pattern: str, value: int, low: int, high: int) -> bool:
+    """Check if a single cron field matches the current value."""
+    if pattern == "*":
+        return True
+
+    # Step: */N
+    step_match = re.match(r"^\*/(\d+)$", pattern)
+    if step_match:
+        step = int(step_match.group(1))
+        return value % step == 0
+
+    # Comma-separated list: 1,5,10
+    for part in pattern.split(","):
+        part = part.strip()
+        # Range: 1-5
+        range_match = re.match(r"^(\d+)-(\d+)$", part)
+        if range_match:
+            lo, hi = int(range_match.group(1)), int(range_match.group(2))
+            if lo <= value <= hi:
+                return True
+            continue
+        # Exact value
+        try:
+            if int(part) == value:
+                return True
+        except ValueError:
+            pass
+
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Scheduler
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SchedulerConfig:
+    """Configuration for the cron scheduler."""
+
+    check_interval_seconds: float = 60.0  # Check every minute
+    max_concurrent_tasks: int = 5
+    enabled: bool = True
+
+
+class CronScheduler:
+    """Background scheduler that triggers cron-scheduled tasks.
+
+    Usage:
+        scheduler = CronScheduler(cron_registry, task_registry)
+        await scheduler.start()
+        # ... later ...
+        await scheduler.stop()
+    """
+
+    def __init__(
+        self,
+        cron_registry: CronRegistry,
+        task_registry: TaskRegistry,
+        config: SchedulerConfig | None = None,
+        on_task_triggered: Callable[[str, TaskPacket], Awaitable[None]] | None = None,
+    ) -> None:
+        self.cron_registry = cron_registry
+        self.task_registry = task_registry
+        self.config = config or SchedulerConfig()
+        self.on_task_triggered = on_task_triggered
+        self._task: asyncio.Task[None] | None = None
+        self._running = False
+
+    async def start(self) -> None:
+        """Start the scheduler loop in the background."""
+        if self._running:
+            return
+        self._running = True
+        self._task = asyncio.create_task(self._loop())
+        logger.info("Cron scheduler started (interval: %.0fs)", self.config.check_interval_seconds)
+
+    async def stop(self) -> None:
+        """Stop the scheduler loop."""
+        self._running = False
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        logger.info("Cron scheduler stopped")
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    async def _loop(self) -> None:
+        """Main scheduler loop — checks cron entries every interval."""
+        while self._running:
+            try:
+                await self._check_and_trigger()
+            except Exception:
+                logger.exception("Scheduler loop error")
+
+            await asyncio.sleep(self.config.check_interval_seconds)
+
+    async def _check_and_trigger(self) -> None:
+        """Check all enabled cron entries and trigger any that are due."""
+        now = datetime.now()
+        now_ms = int(time.time() * 1000)
+
+        for entry in self.cron_registry.enabled_entries():
+            if not cron_matches_now(entry.schedule, now):
+                continue
+
+            # Don't re-trigger within the same minute
+            if entry.last_run_ms > 0:
+                elapsed_ms = now_ms - entry.last_run_ms
+                if elapsed_ms < 55_000:  # Less than 55 seconds since last run
+                    continue
+
+            # Trigger the task
+            logger.info("Cron trigger: %s (schedule: %s)", entry.cron_id, entry.schedule)
+            task_id = self.task_registry.create(entry.packet)
+            self.cron_registry.record_run(entry.cron_id)
+
+            # Notify callback if set
+            if self.on_task_triggered:
+                try:
+                    await self.on_task_triggered(task_id, entry.packet)
+                except Exception:
+                    logger.exception("on_task_triggered callback failed for %s", task_id)
+
+    def status(self) -> dict[str, Any]:
+        """Return scheduler status summary."""
+        entries = self.cron_registry.all_entries()
+        return {
+            "running": self._running,
+            "interval_seconds": self.config.check_interval_seconds,
+            "total_entries": len(entries),
+            "enabled_entries": len([e for e in entries if e.enabled]),
+            "entries": [
+                {
+                    "cron_id": e.cron_id,
+                    "schedule": e.schedule,
+                    "enabled": e.enabled,
+                    "run_count": e.run_count,
+                    "last_run_ms": e.last_run_ms,
+                    "objective": e.packet.objective[:50],
+                }
+                for e in entries
+            ],
+        }
+
+
+# ---------------------------------------------------------------------------
+# Convenience: human-readable schedule descriptions
+# ---------------------------------------------------------------------------
+
+def describe_schedule(expression: str) -> str:
+    """Convert a cron expression to a human-readable description."""
+    parts = expression.strip().split()
+    if len(parts) != 5:
+        return expression
+
+    minute, hour, dom, month, dow = parts
+
+    if expression == "* * * * *":
+        return "Every minute"
+    if minute.startswith("*/"):
+        n = minute[2:]
+        return f"Every {n} minutes"
+    if hour == "*" and minute != "*":
+        return f"Every hour at minute {minute}"
+    if dom == "*" and month == "*" and dow == "*":
+        if hour != "*" and minute != "*":
+            return f"Daily at {hour}:{minute.zfill(2)}"
+    if dow != "*" and dom == "*":
+        days = {"0": "Mon", "1": "Tue", "2": "Wed", "3": "Thu", "4": "Fri", "5": "Sat", "6": "Sun"}
+        day_name = days.get(dow, dow)
+        if hour != "*" and minute != "*":
+            return f"Every {day_name} at {hour}:{minute.zfill(2)}"
+
+    return expression