zwarm 0.1.0__py3-none-any.whl

zwarm/tools/delegation.py

@@ -0,0 +1,357 @@
+"""
+Delegation tools for the orchestrator.
+
+These are the core tools that orchestrators use to delegate work to executors:
+- delegate: Start a new session with an executor
+- converse: Continue a sync conversation
+- check_session: Check status of an async session
+- end_session: End a session
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any, Literal
+
+from wbal.helper import weaveTool
+
+if TYPE_CHECKING:
+    from zwarm.orchestrator import Orchestrator
+
+
+def _truncate(text: str, max_len: int = 200) -> str:
+    """Truncate text with ellipsis."""
+    if len(text) <= max_len:
+        return text
+    return text[:max_len - 3] + "..."
+
+
+def _format_session_header(session_id: str, adapter: str, mode: str) -> str:
+    """Format a nice session header."""
+    return f"[{session_id[:8]}] {adapter} ({mode})"
+
+
+@weaveTool
+def delegate(
+    self: "Orchestrator",
+    task: str,
+    mode: Literal["sync", "async"] = "sync",
+    adapter: str | None = None,
+    model: str | None = None,
+) -> dict[str, Any]:
+    """
+    Delegate work to an executor agent.
+
+    Use this to assign coding tasks to an executor. Two modes available:
+
+    **sync** (default): Start a conversation with the executor.
+    You can iteratively refine requirements using converse().
+    Best for: ambiguous tasks, complex requirements, tasks needing guidance.
+
+    **async**: Fire-and-forget execution.
+    Check progress later with check_session().
+    Best for: clear self-contained tasks, parallel work.
+
+    Args:
+        task: Clear description of what to do. Be specific about requirements.
+        mode: "sync" for conversational, "async" for fire-and-forget.
+        adapter: Which executor adapter to use (default: config setting).
+        model: Model override for the executor.
+
+    Returns:
+        {session_id, status, response (if sync)}
+
+    Example:
+        delegate(task="Add a logout button to the navbar", mode="sync")
+        # Then use converse() to refine: "Also add a confirmation dialog"
+    """
+    # Get adapter (use default from config if not specified)
+    adapter_name = adapter or self.config.executor.adapter
+    executor = self._get_adapter(adapter_name)
+
+    # Run async start_session
+    session = asyncio.get_event_loop().run_until_complete(
+        executor.start_session(
+            task=task,
+            working_dir=self.working_dir,
+            mode=mode,
+            model=model or self.config.executor.model,
+            sandbox=self.config.executor.sandbox,
+        )
+    )
+
+    # Track session
+    self._sessions[session.id] = session
+    self.state.add_session(session)
+
+    # Log events
+    from zwarm.core.models import event_session_started, event_message_sent, Message
+    self.state.log_event(event_session_started(session))
+    self.state.log_event(event_message_sent(session, Message(role="user", content=task)))
+
+    # Get response for sync mode
+    response_text = ""
+    if mode == "sync" and session.messages:
+        response_text = session.messages[-1].content
+        # Log the assistant response too
+        self.state.log_event(event_message_sent(
+            session,
+            Message(role="assistant", content=response_text)
+        ))
+
+    # Build nice result
+    header = _format_session_header(session.id, adapter_name, mode)
+
+    if mode == "sync":
+        return {
+            "success": True,
+            "session": header,
+            "session_id": session.id,
+            "status": "active",
+            "task": _truncate(task, 100),
+            "response": response_text,
+            "hint": "Use converse(session_id, message) to continue this conversation",
+        }
+    else:
+        return {
+            "success": True,
+            "session": header,
+            "session_id": session.id,
+            "status": "running",
+            "task": _truncate(task, 100),
+            "hint": "Use check_session(session_id) to monitor progress",
+        }
+
+
+@weaveTool
+def converse(
+    self: "Orchestrator",
+    session_id: str,
+    message: str,
+) -> dict[str, Any]:
+    """
+    Continue a sync conversation with an executor.
+
+    Use this to iteratively refine requirements, ask for changes,
+    or guide the executor step-by-step. Like chatting with a developer.
+
+    Args:
+        session_id: The session to continue (from delegate() result).
+        message: Your next message to the executor.
+
+    Returns:
+        {session_id, response, turn}
+
+    Example:
+        result = delegate(task="Add user authentication")
+        # Executor responds with initial plan
+        converse(session_id=result["session_id"], message="Use JWT, not sessions")
+        # Executor adjusts approach
+        converse(session_id=result["session_id"], message="Now add tests")
+    """
+    session = self._sessions.get(session_id)
+    if not session:
+        return {
+            "success": False,
+            "error": f"Unknown session: {session_id}",
+            "hint": "Use list_sessions() to see available sessions",
+        }
+
+    if session.mode.value != "sync":
+        return {
+            "success": False,
+            "error": "Cannot converse with async session",
+            "hint": "Use check_session() for async sessions instead",
+        }
+
+    if session.status.value != "active":
+        return {
+            "success": False,
+            "error": f"Session is {session.status.value}, not active",
+            "hint": "Start a new session with delegate()",
+        }
+
+    # Get adapter and send message
+    executor = self._get_adapter(session.adapter)
+    try:
+        response = asyncio.get_event_loop().run_until_complete(
+            executor.send_message(session, message)
+        )
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+            "session_id": session_id,
+        }
+
+    # Update state
+    self.state.update_session(session)
+
+    # Log both messages
+    from zwarm.core.models import event_message_sent, Message
+    self.state.log_event(event_message_sent(session, Message(role="user", content=message)))
+    self.state.log_event(event_message_sent(session, Message(role="assistant", content=response)))
+
+    # Calculate turn number
+    turn = len([m for m in session.messages if m.role == "user"])
+    header = _format_session_header(session.id, session.adapter, session.mode.value)
+
+    return {
+        "success": True,
+        "session": header,
+        "session_id": session_id,
+        "turn": turn,
+        "you_said": _truncate(message, 100),
+        "response": response,
+    }
+
+
+@weaveTool
+def check_session(
+    self: "Orchestrator",
+    session_id: str,
+) -> dict[str, Any]:
+    """
+    Check the status of a session.
+
+    For async sessions: Check if the executor has finished.
+    For sync sessions: Get current status and message count.
+
+    Args:
+        session_id: The session to check.
+
+    Returns:
+        {session_id, status, ...}
+    """
+    session = self._sessions.get(session_id)
+    if not session:
+        return {
+            "success": False,
+            "error": f"Unknown session: {session_id}",
+            "hint": "Use list_sessions() to see available sessions",
+        }
+
+    executor = self._get_adapter(session.adapter)
+    status = asyncio.get_event_loop().run_until_complete(
+        executor.check_status(session)
+    )
+
+    # Update state if status changed
+    self.state.update_session(session)
+
+    header = _format_session_header(session.id, session.adapter, session.mode.value)
+
+    return {
+        "success": True,
+        "session": header,
+        "session_id": session_id,
+        "mode": session.mode.value,
+        "status": session.status.value,
+        "messages": len(session.messages),
+        "task": _truncate(session.task_description, 80),
+        **status,
+    }
+
+
+@weaveTool
+def end_session(
+    self: "Orchestrator",
+    session_id: str,
+    verdict: Literal["completed", "failed", "cancelled"] = "completed",
+    summary: str | None = None,
+) -> dict[str, Any]:
+    """
+    End a session with a verdict.
+
+    Call this when:
+    - Task is done (verdict="completed")
+    - Task failed and you're giving up (verdict="failed")
+    - You want to stop early (verdict="cancelled")
+
+    Args:
+        session_id: The session to end.
+        verdict: How the session ended.
+        summary: Optional summary of what was accomplished.
+
+    Returns:
+        {session_id, status, summary}
+    """
+    session = self._sessions.get(session_id)
+    if not session:
+        return {
+            "success": False,
+            "error": f"Unknown session: {session_id}",
+        }
+
+    # Stop the session if still running
+    if session.status.value == "active":
+        executor = self._get_adapter(session.adapter)
+        if verdict == "completed":
+            session.complete(summary)
+        else:
+            asyncio.get_event_loop().run_until_complete(executor.stop(session))
+            if verdict == "failed":
+                session.fail(summary)
+            else:
+                session.fail(f"Cancelled: {summary}" if summary else "Cancelled")
+
+    # Update state
+    self.state.update_session(session)
+
+    # Log event
+    from zwarm.core.models import event_session_completed
+    self.state.log_event(event_session_completed(session))
+
+    header = _format_session_header(session.id, session.adapter, session.mode.value)
+    verdict_icon = {"completed": "✓", "failed": "✗", "cancelled": "○"}.get(verdict, "?")
+
+    return {
+        "success": True,
+        "session": header,
+        "session_id": session_id,
+        "verdict": f"{verdict_icon} {verdict}",
+        "summary": session.exit_message or "(no summary)",
+        "total_turns": len([m for m in session.messages if m.role == "user"]),
+    }
+
+
+@weaveTool
+def list_sessions(
+    self: "Orchestrator",
+    status: str | None = None,
+) -> dict[str, Any]:
+    """
+    List all sessions, optionally filtered by status.
+
+    Args:
+        status: Filter by status ("active", "completed", "failed").
+
+    Returns:
+        {sessions: [...], count}
+    """
+    sessions = self.state.list_sessions(status=status)
+
+    session_list = []
+    for s in sessions:
+        status_icon = {
+            "active": "●",
+            "completed": "✓",
+            "failed": "✗",
+        }.get(s.status.value, "?")
+
+        session_list.append({
+            "id": s.id[:8] + "...",
+            "full_id": s.id,
+            "status": f"{status_icon} {s.status.value}",
+            "adapter": s.adapter,
+            "mode": s.mode.value,
+            "task": _truncate(s.task_description, 60),
+            "turns": len([m for m in s.messages if m.role == "user"]),
+        })
+
+    return {
+        "success": True,
+        "sessions": session_list,
+        "count": len(sessions),
+        "filter": status or "all",
+    }

zwarm/watchers/__init__.py

@@ -0,0 +1,26 @@
+"""
+Watchers: Trajectory aligners for agent behavior.
+
+Watchers observe agent activity and can intervene to correct course.
+They are composable and can be layered.
+"""
+
+from zwarm.watchers.base import Watcher, WatcherContext, WatcherResult, WatcherAction
+from zwarm.watchers.registry import register_watcher, get_watcher, list_watchers
+from zwarm.watchers.manager import WatcherManager, WatcherConfig, build_watcher_manager
+
+# Import built-in watchers to register them
+from zwarm.watchers import builtin as _builtin  # noqa: F401
+
+__all__ = [
+    "Watcher",
+    "WatcherContext",
+    "WatcherResult",
+    "WatcherAction",
+    "WatcherConfig",
+    "WatcherManager",
+    "register_watcher",
+    "get_watcher",
+    "list_watchers",
+    "build_watcher_manager",
+]

zwarm/watchers/base.py

@@ -0,0 +1,131 @@
+"""
+Base watcher interface and types.
+
+Watchers observe agent trajectories and can intervene to correct course.
+They're designed to be:
+- Composable: Layer multiple watchers for different concerns
+- Non-blocking: Check asynchronously, don't slow down the agent
+- Actionable: Return clear guidance when correction is needed
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class WatcherAction(str, Enum):
+    """What action to take based on watcher observation."""
+
+    CONTINUE = "continue"  # Keep going, trajectory looks good
+    NUDGE = "nudge"  # Insert guidance into next prompt
+    PAUSE = "pause"  # Pause for human review
+    ABORT = "abort"  # Stop execution immediately
+
+
+@dataclass
+class WatcherContext:
+    """
+    Context provided to watchers for observation.
+
+    Contains everything a watcher might need to evaluate trajectory.
+    """
+
+    # Current orchestrator state
+    task: str  # Original task
+    step: int  # Current step number
+    max_steps: int  # Maximum steps allowed
+    messages: list[dict[str, Any]]  # Conversation history
+
+    # Session activity
+    sessions: list[dict[str, Any]] = field(default_factory=list)
+    events: list[dict[str, Any]] = field(default_factory=list)
+
+    # Working directory context
+    working_dir: str | None = None
+    files_changed: list[str] = field(default_factory=list)
+
+    # Custom metadata
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class WatcherResult:
+    """
+    Result from a watcher observation.
+
+    Contains the recommended action and any guidance to inject.
+    """
+
+    action: WatcherAction = WatcherAction.CONTINUE
+    reason: str = ""  # Why this action was recommended
+    guidance: str = ""  # Message to inject if action is NUDGE
+    priority: int = 0  # Higher priority watchers take precedence
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @staticmethod
+    def ok() -> "WatcherResult":
+        """Trajectory looks good, continue."""
+        return WatcherResult(action=WatcherAction.CONTINUE)
+
+    @staticmethod
+    def nudge(guidance: str, reason: str = "", priority: int = 0) -> "WatcherResult":
+        """Insert guidance to correct trajectory."""
+        return WatcherResult(
+            action=WatcherAction.NUDGE,
+            guidance=guidance,
+            reason=reason,
+            priority=priority,
+        )
+
+    @staticmethod
+    def pause(reason: str, priority: int = 0) -> "WatcherResult":
+        """Pause for human review."""
+        return WatcherResult(
+            action=WatcherAction.PAUSE,
+            reason=reason,
+            priority=priority,
+        )
+
+    @staticmethod
+    def abort(reason: str, priority: int = 100) -> "WatcherResult":
+        """Stop execution immediately."""
+        return WatcherResult(
+            action=WatcherAction.ABORT,
+            reason=reason,
+            priority=priority,
+        )
+
+
+class Watcher(ABC):
+    """
+    Base class for watchers.
+
+    Watchers observe agent trajectories and provide guidance when needed.
+    They're designed to be stateless - all context comes from WatcherContext.
+    """
+
+    name: str = "base"
+    description: str = ""
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        """Initialize watcher with optional config."""
+        self.config = config or {}
+
+    @abstractmethod
+    async def observe(self, ctx: WatcherContext) -> WatcherResult:
+        """
+        Observe the current trajectory and decide action.
+
+        Args:
+            ctx: Current context with all trajectory info
+
+        Returns:
+            WatcherResult with recommended action
+        """
+        ...
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}({self.name})>"