athanore 0.0.1__py3-none-any.whl

athanore/__init__.py

@@ -0,0 +1,23 @@
+from athanore.dispatcher import AgentDispatcher
+from athanore.queue_adapters.base import Queue, QueueAdapter, Task, TaskComment
+from athanore.queue_adapters.json_file import JsonFileAdapter
+from athanore.agent_adapters.base import AgentAdapter, AgentContext, AgentEvent, AgentResult, AgentStatus, EventCallback
+from athanore.agent_adapters.subprocess_adapter import SubprocessAgentAdapter
+from athanore.event_bus import EventBus
+
+__all__ = [
+    "AgentDispatcher",
+    "AgentAdapter",
+    "AgentContext",
+    "AgentEvent",
+    "AgentResult",
+    "AgentStatus",
+    "EventBus",
+    "EventCallback",
+    "SubprocessAgentAdapter",
+    "JsonFileAdapter",
+    "Queue",
+    "Task",
+    "QueueAdapter",
+    "TaskComment",
+]

athanore/agent_adapters/__init__.py

@@ -0,0 +1 @@
+# Agent adapters for different agent types

athanore/agent_adapters/base.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from athanore.config import RouteConfig
+    from athanore.queue_adapters.base import QueueAdapter, Task
+
+
+@dataclass
+class AgentEvent:
+    """A single event emitted by an agent adapter during execution."""
+    task_id: str
+    event_type: str      # "lifecycle", "output", "info"
+    data: dict[str, Any]
+    timestamp: float = field(default_factory=time.time)
+    sequence: int = 0          # set by EventBus (per-task)
+    global_sequence: int = -1  # set by EventBus (global stream, -1 = not published globally)
+
+
+EventCallback = Callable[[AgentEvent], None]
+
+
+@dataclass
+class AgentContext:
+    task: Task
+    route: RouteConfig
+    queue_adapter: QueueAdapter
+    prompt: str
+    timeout: int | None = None
+    event_callback: EventCallback | None = None
+
+
+@dataclass
+class AgentResult:
+    success: bool
+    exit_code: int | None = None
+    timed_out: bool = False
+    cancelled: bool = False
+    error_message: str = ""
+
+
+@dataclass
+class AgentStatus:
+    task_id: str
+    started_at: float
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+class AgentAdapter(Protocol):
+    async def run(self, context: AgentContext) -> AgentResult: ...
+    def get_status(self) -> dict[str, AgentStatus]: ...

athanore/agent_adapters/subprocess_adapter.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from athanore.agent_adapters.base import AgentContext, AgentEvent, AgentResult, AgentStatus
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class _RunningAgent:
+    task_id: str
+    process: asyncio.subprocess.Process
+    command_str: str = ""
+    started_at: float = field(default_factory=time.time)
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+class SubprocessAgentAdapter:
+    """Agent adapter that manages agents as subprocesses.
+
+    Owns the full lifecycle: spawn, monitor stdout, enforce timeouts, cleanup.
+    Subclass and override hook methods to customize behavior.
+    """
+
+    def __init__(self) -> None:
+        self._running: dict[str, _RunningAgent] = {}
+
+    def build_command(self, context: AgentContext) -> list[str]:
+        """Build the command to execute.
+
+        Default: uses context.route.format_command() with task details.
+        """
+        return context.route.format_command(
+            task_id=context.task.id,
+            task_name=context.task.name,
+            task_url=context.task.url,
+        )
+
+    def process_stdout_line(
+        self, line: str, running: _RunningAgent, context: AgentContext
+    ) -> None:
+        """Handle a single line of stdout. No-op by default."""
+        pass
+
+    def format_spawn_comment(
+        self, command_str: str, context: AgentContext
+    ) -> str:
+        """Format the comment posted when spawning an agent."""
+        return f"Spawning agent with command `{command_str}`"
+
+    def format_exit_comment(
+        self, running: _RunningAgent, result: AgentResult, context: AgentContext
+    ) -> str:
+        """Format the comment posted when an agent exits."""
+        if result.timed_out:
+            return f"Agent session ended: timed out after {context.timeout}s"
+        elif result.cancelled:
+            return "Agent session ended: cancelled"
+        elif result.exit_code == 0:
+            return "Agent session ended normally (exit 0)"
+        else:
+            return f"Agent session ended: exit code {result.exit_code}: {result.error_message}"
+
+    def get_agent_extras(self, running: _RunningAgent) -> dict[str, Any]:
+        """Return adapter-specific extras for status reporting. Empty by default."""
+        return {}
+
+    @staticmethod
+    def _emit(context: AgentContext, event_type: str, data: dict[str, Any]) -> None:
+        """Emit an event via context.event_callback, if set."""
+        if context.event_callback is not None:
+            try:
+                context.event_callback(AgentEvent(
+                    task_id=context.task.id,
+                    event_type=event_type,
+                    data=data,
+                ))
+            except Exception:
+                log.warning("Error emitting event for task %s", context.task.id, exc_info=True)
+
+    async def run(self, context: AgentContext) -> AgentResult:
+        """Full agent lifecycle: spawn, monitor, enforce timeout, cleanup."""
+        cmd = self.build_command(context)
+        command_str = " ".join(cmd)
+
+        # Post spawn comment
+        try:
+            comment = self.format_spawn_comment(command_str, context)
+            context.queue_adapter.add_comment(context.task.id, comment)
+        except Exception:
+            log.warning("Failed to add spawn comment for task %s", context.task.id, exc_info=True)
+
+        log.info("Spawning agent for task %s: %s", context.task.id, cmd)
+        process = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+        )
+
+        running = _RunningAgent(
+            task_id=context.task.id,
+            process=process,
+            command_str=command_str,
+            started_at=time.time(),
+        )
+        self._running[context.task.id] = running
+        log.debug("Slot acquired: task=%s pid=%s", context.task.id, process.pid)
+        self._emit(context, "lifecycle", {"status": "spawned", "pid": process.pid})
+
+        timed_out = False
+        cancelled = False
+        stdout_task = None
+
+        async def read_stdout() -> None:
+            if process.stdout:
+                try:
+                    async for raw_line in process.stdout:
+                        line = raw_line.decode(errors="replace").strip()
+                        try:
+                            self.process_stdout_line(line, running, context)
+                        except Exception:
+                            log.warning("Error processing stdout line for task %s", context.task.id, exc_info=True)
+                        self._emit(context, "output", {"text": line, "source": "stdout"})
+                except asyncio.CancelledError:
+                    pass
+
+        try:
+            stdout_task = asyncio.create_task(read_stdout())
+
+            if context.timeout is not None:
+                try:
+                    await asyncio.wait_for(process.wait(), timeout=context.timeout)
+                except TimeoutError:
+                    timed_out = True
+                    log.warning("Agent for task %s timed out after %d seconds", context.task.id, context.timeout)
+                    try:
+                        process.terminate()
+                    except ProcessLookupError:
+                        log.debug("Process for task %s already exited before terminate", context.task.id)
+                    try:
+                        await asyncio.wait_for(process.wait(), timeout=5)
+                    except TimeoutError:
+                        log.warning("Agent for task %s did not terminate gracefully, killing", context.task.id)
+                        try:
+                            process.kill()
+                        except ProcessLookupError:
+                            log.debug("Process for task %s already exited before kill", context.task.id)
+                        try:
+                            await asyncio.wait_for(process.wait(), timeout=10)
+                        except TimeoutError:
+                            log.error("Process for task %s did not exit after SIGKILL, forcibly releasing slot", context.task.id)
+            else:
+                await process.wait()
+
+            rc = process.returncode
+            log.info("Agent for task %s exited with code %s", context.task.id, rc)
+
+        except asyncio.CancelledError:
+            cancelled = True
+            log.info("Agent cancelled for task %s, terminating process", context.task.id)
+            try:
+                process.terminate()
+            except ProcessLookupError:
+                pass
+            try:
+                await asyncio.wait_for(process.wait(), timeout=5)
+            except TimeoutError:
+                try:
+                    process.kill()
+                except ProcessLookupError:
+                    pass
+                try:
+                    await asyncio.wait_for(process.wait(), timeout=10)
+                except TimeoutError:
+                    log.error("Process for task %s did not exit after SIGKILL, forcibly releasing slot", context.task.id)
+
+        finally:
+            # Clean up stdout reader
+            if stdout_task is not None and not stdout_task.done():
+                stdout_task.cancel()
+                try:
+                    await stdout_task
+                except asyncio.CancelledError:
+                    pass
+            elif stdout_task is not None:
+                try:
+                    await asyncio.wait_for(stdout_task, timeout=5)
+                except Exception:
+                    log.warning("Error awaiting stdout reader for task %s", context.task.id, exc_info=True)
+
+            # Update extras before building result
+            running.extras = self.get_agent_extras(running)
+
+            rc = process.returncode or 0
+            result = AgentResult(
+                success=not timed_out and not cancelled and rc == 0,
+                exit_code=rc,
+                timed_out=timed_out,
+                cancelled=cancelled,
+            )
+
+            if timed_out:
+                self._emit(context, "lifecycle", {"status": "timeout", "exit_code": rc})
+            elif cancelled:
+                self._emit(context, "lifecycle", {"status": "cancelled"})
+            elif rc == 0:
+                self._emit(context, "lifecycle", {"status": "completed", "exit_code": rc})
+            else:
+                self._emit(context, "lifecycle", {"status": "error", "exit_code": rc})
+
+            # Post exit comment
+            try:
+                comment = self.format_exit_comment(running, result, context)
+                context.queue_adapter.add_comment(context.task.id, comment)
+            except Exception:
+                log.warning("Failed to add exit comment for task %s", context.task.id, exc_info=True)
+
+            self._running.pop(context.task.id, None)
+
+        return result
+
+    def get_status(self) -> dict[str, AgentStatus]:
+        """Return status for all currently running agents."""
+        statuses: dict[str, AgentStatus] = {}
+        for task_id, running in self._running.items():
+            extras = self.get_agent_extras(running)
+            extras["pid"] = running.process.pid
+            extras["command"] = running.command_str
+            statuses[task_id] = AgentStatus(
+                task_id=task_id,
+                started_at=running.started_at,
+                extras=extras,
+            )
+        return statuses

athanore/config.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from athanore.agent_adapters.base import AgentAdapter
+
+
+@dataclass
+class RouteConfig:
+    queue_name: str
+    command: str = ""
+    args: list[str] = field(default_factory=list)
+    in_progress_queue: str = "In Progress"
+    timeout: int | None = None  # timeout in seconds, None = no timeout
+    poll_interval: int | None = None  # per-queue poll interval in seconds, None = use global
+    priority: int | None = None  # dispatch priority, lower = higher priority, None = use registration index
+    max_retries: int | None = None  # max retry attempts, None = use dispatcher default
+    dead_letter_queue: str | None = None  # queue for tasks that exhaust retries, None = use dispatcher default
+    prompt_fn: Callable[[str, str], str] | None = None  # (task_id, task_name) -> prompt string
+    agent: Any = None  # per-route AgentAdapter, None = use default
+
+    def format_command(
+        self,
+        task_id: str,
+        task_name: str,
+        task_url: str = "",
+    ) -> list[str]:
+        replacements = {
+            "{task_id}": task_id,
+            "{task_name}": task_name,
+            "{task_url}": task_url,
+        }
+        formatted_args = []
+        for arg in self.args:
+            for placeholder, value in replacements.items():
+                arg = arg.replace(placeholder, value)
+            formatted_args.append(arg)
+
+        cmd = [self.command, *formatted_args] if self.command else list(formatted_args)
+
+        if self.prompt_fn is not None:
+            prompt = self.prompt_fn(task_id, task_name)
+            cmd.append(prompt)
+
+        return cmd