zwarm 0.1.0__py3-none-any.whl

zwarm/core/config.py

@@ -0,0 +1,271 @@
+"""
+Configuration system for zwarm.
+
+Supports:
+- config.toml for user settings (weave project, defaults)
+- .env for environment variables
+- Composable YAML configs with inheritance (extends:)
+- CLI overrides via --set key=value
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+from dotenv import load_dotenv
+
+
+@dataclass
+class WeaveConfig:
+    """Weave integration settings."""
+
+    project: str | None = None
+    enabled: bool = True
+
+
+@dataclass
+class ExecutorConfig:
+    """Configuration for an executor (coding agent)."""
+
+    adapter: str = "codex_mcp"  # codex_mcp | codex_exec | claude_code
+    model: str | None = None
+    sandbox: str = "workspace-write"  # read-only | workspace-write | danger-full-access
+    timeout: int = 3600
+
+
+@dataclass
+class OrchestratorConfig:
+    """Configuration for the orchestrator."""
+
+    lm: str = "gpt-5-mini"
+    prompt: str | None = None  # path to prompt yaml
+    tools: list[str] = field(default_factory=lambda: ["delegate", "converse", "check_session", "end_session", "bash"])
+    max_steps: int = 50
+    parallel_delegations: int = 4
+    sync_first: bool = True  # prefer sync mode by default
+
+
+@dataclass
+class WatcherConfigItem:
+    """Configuration for a single watcher."""
+
+    name: str
+    enabled: bool = True
+    config: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class WatchersConfig:
+    """Configuration for watchers."""
+
+    enabled: bool = True
+    watchers: list[WatcherConfigItem] = field(default_factory=lambda: [
+        WatcherConfigItem(name="progress"),
+        WatcherConfigItem(name="budget"),
+    ])
+
+
+@dataclass
+class ZwarmConfig:
+    """Root configuration for zwarm."""
+
+    weave: WeaveConfig = field(default_factory=WeaveConfig)
+    executor: ExecutorConfig = field(default_factory=ExecutorConfig)
+    orchestrator: OrchestratorConfig = field(default_factory=OrchestratorConfig)
+    watchers: WatchersConfig = field(default_factory=WatchersConfig)
+    state_dir: str = ".zwarm"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ZwarmConfig:
+        """Create config from dictionary."""
+        weave_data = data.get("weave", {})
+        executor_data = data.get("executor", {})
+        orchestrator_data = data.get("orchestrator", {})
+        watchers_data = data.get("watchers", {})
+
+        # Parse watchers config
+        watchers_config = WatchersConfig(
+            enabled=watchers_data.get("enabled", True),
+            watchers=[
+                WatcherConfigItem(**w) if isinstance(w, dict) else w
+                for w in watchers_data.get("watchers", [])
+            ] or WatchersConfig().watchers,
+        )
+
+        return cls(
+            weave=WeaveConfig(**weave_data) if weave_data else WeaveConfig(),
+            executor=ExecutorConfig(**executor_data) if executor_data else ExecutorConfig(),
+            orchestrator=OrchestratorConfig(**orchestrator_data) if orchestrator_data else OrchestratorConfig(),
+            watchers=watchers_config,
+            state_dir=data.get("state_dir", ".zwarm"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "weave": {
+                "project": self.weave.project,
+                "enabled": self.weave.enabled,
+            },
+            "executor": {
+                "adapter": self.executor.adapter,
+                "model": self.executor.model,
+                "sandbox": self.executor.sandbox,
+                "timeout": self.executor.timeout,
+            },
+            "orchestrator": {
+                "lm": self.orchestrator.lm,
+                "prompt": self.orchestrator.prompt,
+                "tools": self.orchestrator.tools,
+                "max_steps": self.orchestrator.max_steps,
+                "parallel_delegations": self.orchestrator.parallel_delegations,
+                "sync_first": self.orchestrator.sync_first,
+            },
+            "watchers": {
+                "enabled": self.watchers.enabled,
+                "watchers": [
+                    {"name": w.name, "enabled": w.enabled, "config": w.config}
+                    for w in self.watchers.watchers
+                ],
+            },
+            "state_dir": self.state_dir,
+        }
+
+
+def load_env(path: Path | None = None) -> None:
+    """Load .env file if it exists."""
+    if path is None:
+        path = Path.cwd() / ".env"
+    if path.exists():
+        load_dotenv(path)
+
+
+def load_toml_config(path: Path | None = None) -> dict[str, Any]:
+    """Load config.toml file."""
+    if path is None:
+        path = Path.cwd() / "config.toml"
+    if not path.exists():
+        return {}
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def load_yaml_config(path: Path) -> dict[str, Any]:
+    """
+    Load YAML config with inheritance support.
+
+    Supports 'extends: path/to/base.yaml' for composition.
+    """
+    if not path.exists():
+        raise FileNotFoundError(f"Config not found: {path}")
+
+    with open(path) as f:
+        data = yaml.safe_load(f) or {}
+
+    # Handle inheritance
+    extends = data.pop("extends", None)
+    if extends:
+        base_path = (path.parent / extends).resolve()
+        base_data = load_yaml_config(base_path)
+        # Deep merge: data overrides base
+        data = deep_merge(base_data, data)
+
+    return data
+
+
+def deep_merge(base: dict, override: dict) -> dict:
+    """Deep merge two dicts, with override taking precedence."""
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def apply_overrides(config: dict[str, Any], overrides: list[str]) -> dict[str, Any]:
+    """
+    Apply CLI overrides in format 'key.path=value'.
+
+    Example: 'orchestrator.lm=claude-sonnet' sets config['orchestrator']['lm'] = 'claude-sonnet'
+    """
+    result = config.copy()
+    for override in overrides:
+        if "=" not in override:
+            continue
+        key_path, value = override.split("=", 1)
+        keys = key_path.split(".")
+
+        # Parse value (try int, float, bool, then string)
+        parsed_value: Any = value
+        if value.lower() == "true":
+            parsed_value = True
+        elif value.lower() == "false":
+            parsed_value = False
+        else:
+            try:
+                parsed_value = int(value)
+            except ValueError:
+                try:
+                    parsed_value = float(value)
+                except ValueError:
+                    pass  # Keep as string
+
+        # Navigate and set
+        target = result
+        for key in keys[:-1]:
+            if key not in target:
+                target[key] = {}
+            target = target[key]
+        target[keys[-1]] = parsed_value
+
+    return result
+
+
+def load_config(
+    config_path: Path | None = None,
+    toml_path: Path | None = None,
+    env_path: Path | None = None,
+    overrides: list[str] | None = None,
+) -> ZwarmConfig:
+    """
+    Load configuration with full precedence chain:
+    1. Defaults (in dataclasses)
+    2. config.toml (user settings)
+    3. YAML config file (if provided)
+    4. CLI overrides (--set key=value)
+    5. Environment variables (for secrets)
+    """
+    # Load .env first (for secrets)
+    load_env(env_path)
+
+    # Start with defaults
+    config_dict: dict[str, Any] = {}
+
+    # Layer in config.toml
+    toml_config = load_toml_config(toml_path)
+    if toml_config:
+        config_dict = deep_merge(config_dict, toml_config)
+
+    # Layer in YAML config
+    if config_path and config_path.exists():
+        yaml_config = load_yaml_config(config_path)
+        config_dict = deep_merge(config_dict, yaml_config)
+
+    # Apply CLI overrides
+    if overrides:
+        config_dict = apply_overrides(config_dict, overrides)
+
+    # Apply environment variables for weave
+    if os.getenv("WEAVE_PROJECT"):
+        if "weave" not in config_dict:
+            config_dict["weave"] = {}
+        config_dict["weave"]["project"] = os.getenv("WEAVE_PROJECT")
+
+    return ZwarmConfig.from_dict(config_dict)

zwarm/core/environment.py

@@ -0,0 +1,83 @@
+"""
+OrchestratorEnv: A lean environment for the zwarm orchestrator.
+
+Unlike ChatEnv, this environment:
+- Has no notes/observations (we use StateManager instead)
+- Has no chat() tool (orchestrator communicates via output_handler)
+- Shows active sessions in observe() for context
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, TYPE_CHECKING
+
+from wbal.environment import Environment
+
+if TYPE_CHECKING:
+    from zwarm.core.models import ConversationSession
+
+
+class OrchestratorEnv(Environment):
+    """
+    Lean environment for the orchestrator agent.
+
+    Provides:
+    - Task context
+    - Working directory info
+    - Active session visibility
+    - Output handler for messages
+    """
+
+    task: str = ""
+    working_dir: Path = Path(".")
+    output_handler: Callable[[str], None] = lambda x: print(x)
+
+    # Session tracking (set by orchestrator)
+    _sessions: dict[str, "ConversationSession"] | None = None
+
+    def set_sessions(self, sessions: dict[str, "ConversationSession"]) -> None:
+        """Set the sessions dict for observe() visibility."""
+        self._sessions = sessions
+
+    def observe(self) -> str:
+        """
+        Return observable state for the orchestrator.
+
+        Shows:
+        - Current task
+        - Working directory
+        - Active sessions with their status
+        """
+        parts = []
+
+        # Task
+        if self.task:
+            parts.append(f"## Current Task\n{self.task}")
+
+        # Working directory
+        parts.append(f"## Working Directory\n{self.working_dir.absolute()}")
+
+        # Active sessions
+        if self._sessions:
+            session_lines = []
+            for sid, session in self._sessions.items():
+                status_icon = {
+                    "active": "[ACTIVE]",
+                    "completed": "[DONE]",
+                    "failed": "[FAILED]",
+                }.get(session.status.value, "[?]")
+
+                mode_icon = "sync" if session.mode.value == "sync" else "async"
+                task_preview = session.task_description[:60] + "..." if len(session.task_description) > 60 else session.task_description
+
+                session_lines.append(
+                    f"  - {sid[:8]}... {status_icon} ({mode_icon}, {session.adapter}) {task_preview}"
+                )
+
+            if session_lines:
+                parts.append("## Sessions\n" + "\n".join(session_lines))
+            else:
+                parts.append("## Sessions\n  (none)")
+
+        return "\n\n".join(parts)

zwarm/core/models.py

@@ -0,0 +1,299 @@
+"""
+Core models for zwarm.
+
+These are the fundamental data structures:
+- ConversationSession: A session with an executor agent (sync or async)
+- Task: A unit of work that may be delegated
+- Event: An append-only log entry for audit/debugging
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Literal
+from uuid import uuid4
+
+
+class SessionMode(str, Enum):
+    """Execution mode for a session."""
+
+    SYNC = "sync"
+    ASYNC = "async"
+
+
+class SessionStatus(str, Enum):
+    """Status of a conversation session."""
+
+    ACTIVE = "active"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class TaskStatus(str, Enum):
+    """Status of a task."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class Message:
+    """A single message in a conversation."""
+
+    role: Literal["user", "assistant", "system"]
+    content: str
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "role": self.role,
+            "content": self.content,
+            "timestamp": self.timestamp.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Message:
+        return cls(
+            role=data["role"],
+            content=data["content"],
+            timestamp=datetime.fromisoformat(data["timestamp"]) if "timestamp" in data else datetime.now(),
+        )
+
+
+@dataclass
+class ConversationSession:
+    """
+    A conversational session with an executor agent.
+
+    Supports both sync (iterative conversation) and async (fire-and-forget) modes.
+    """
+
+    id: str = field(default_factory=lambda: str(uuid4()))
+    adapter: str = "codex_mcp"  # codex_mcp | codex_exec | claude_code
+    mode: SessionMode = SessionMode.SYNC
+    status: SessionStatus = SessionStatus.ACTIVE
+    working_dir: Path = field(default_factory=Path.cwd)
+    messages: list[Message] = field(default_factory=list)
+    started_at: datetime = field(default_factory=datetime.now)
+    completed_at: datetime | None = None
+
+    # Adapter-specific handles (not serialized)
+    conversation_id: str | None = None  # MCP conversationId for codex
+    process: subprocess.Popen | None = field(default=None, repr=False)
+
+    # Metadata
+    task_description: str = ""
+    model: str | None = None
+    exit_message: str | None = None
+
+    def add_message(self, role: Literal["user", "assistant", "system"], content: str) -> Message:
+        """Add a message to the conversation."""
+        msg = Message(role=role, content=content)
+        self.messages.append(msg)
+        return msg
+
+    def complete(self, exit_message: str | None = None) -> None:
+        """Mark session as completed."""
+        self.status = SessionStatus.COMPLETED
+        self.completed_at = datetime.now()
+        self.exit_message = exit_message
+
+    def fail(self, error: str | None = None) -> None:
+        """Mark session as failed."""
+        self.status = SessionStatus.FAILED
+        self.completed_at = datetime.now()
+        self.exit_message = error
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary (for persistence)."""
+        return {
+            "id": self.id,
+            "adapter": self.adapter,
+            "mode": self.mode.value,
+            "status": self.status.value,
+            "working_dir": str(self.working_dir),
+            "messages": [m.to_dict() for m in self.messages],
+            "started_at": self.started_at.isoformat(),
+            "completed_at": self.completed_at.isoformat() if self.completed_at else None,
+            "conversation_id": self.conversation_id,
+            "task_description": self.task_description,
+            "model": self.model,
+            "exit_message": self.exit_message,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ConversationSession:
+        """Deserialize from dictionary."""
+        return cls(
+            id=data["id"],
+            adapter=data.get("adapter", "codex_mcp"),
+            mode=SessionMode(data["mode"]),
+            status=SessionStatus(data["status"]),
+            working_dir=Path(data["working_dir"]),
+            messages=[Message.from_dict(m) for m in data.get("messages", [])],
+            started_at=datetime.fromisoformat(data["started_at"]),
+            completed_at=datetime.fromisoformat(data["completed_at"]) if data.get("completed_at") else None,
+            conversation_id=data.get("conversation_id"),
+            task_description=data.get("task_description", ""),
+            model=data.get("model"),
+            exit_message=data.get("exit_message"),
+        )
+
+
+@dataclass
+class Task:
+    """
+    A unit of work that may be delegated to an executor.
+
+    Tasks track what needs to be done and link to the session doing the work.
+    """
+
+    id: str = field(default_factory=lambda: str(uuid4()))
+    description: str = ""
+    status: TaskStatus = TaskStatus.PENDING
+    session_id: str | None = None
+    created_at: datetime = field(default_factory=datetime.now)
+    completed_at: datetime | None = None
+    result: str | None = None
+    parent_task_id: str | None = None  # For subtasks
+
+    def start(self, session_id: str) -> None:
+        """Mark task as started with a session."""
+        self.status = TaskStatus.IN_PROGRESS
+        self.session_id = session_id
+
+    def complete(self, result: str | None = None) -> None:
+        """Mark task as completed."""
+        self.status = TaskStatus.COMPLETED
+        self.completed_at = datetime.now()
+        self.result = result
+
+    def fail(self, error: str | None = None) -> None:
+        """Mark task as failed."""
+        self.status = TaskStatus.FAILED
+        self.completed_at = datetime.now()
+        self.result = error
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "description": self.description,
+            "status": self.status.value,
+            "session_id": self.session_id,
+            "created_at": self.created_at.isoformat(),
+            "completed_at": self.completed_at.isoformat() if self.completed_at else None,
+            "result": self.result,
+            "parent_task_id": self.parent_task_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Task:
+        return cls(
+            id=data["id"],
+            description=data["description"],
+            status=TaskStatus(data["status"]),
+            session_id=data.get("session_id"),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            completed_at=datetime.fromisoformat(data["completed_at"]) if data.get("completed_at") else None,
+            result=data.get("result"),
+            parent_task_id=data.get("parent_task_id"),
+        )
+
+
+@dataclass
+class Event:
+    """
+    An append-only log entry for audit and debugging.
+
+    Events capture everything that happens in the system.
+    """
+
+    id: str = field(default_factory=lambda: str(uuid4()))
+    timestamp: datetime = field(default_factory=datetime.now)
+    kind: str = ""  # session_started, message_sent, task_completed, etc.
+    session_id: str | None = None
+    task_id: str | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "timestamp": self.timestamp.isoformat(),
+            "kind": self.kind,
+            "session_id": self.session_id,
+            "task_id": self.task_id,
+            "payload": self.payload,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Event:
+        return cls(
+            id=data["id"],
+            timestamp=datetime.fromisoformat(data["timestamp"]),
+            kind=data["kind"],
+            session_id=data.get("session_id"),
+            task_id=data.get("task_id"),
+            payload=data.get("payload", {}),
+        )
+
+
+# Event factory functions for common event types
+def event_session_started(session: ConversationSession) -> Event:
+    return Event(
+        kind="session_started",
+        session_id=session.id,
+        payload={
+            "adapter": session.adapter,
+            "mode": session.mode.value,
+            "task": session.task_description,
+        },
+    )
+
+
+def event_message_sent(session: ConversationSession, message: Message) -> Event:
+    return Event(
+        kind="message_sent",
+        session_id=session.id,
+        payload={
+            "role": message.role,
+            "content": message.content[:500],  # Truncate for log
+        },
+    )
+
+
+def event_session_completed(session: ConversationSession) -> Event:
+    return Event(
+        kind="session_completed",
+        session_id=session.id,
+        payload={
+            "status": session.status.value,
+            "exit_message": session.exit_message,
+            "message_count": len(session.messages),
+        },
+    )
+
+
+def event_task_created(task: Task) -> Event:
+    return Event(
+        kind="task_created",
+        task_id=task.id,
+        payload={"description": task.description},
+    )
+
+
+def event_task_completed(task: Task) -> Event:
+    return Event(
+        kind="task_completed",
+        task_id=task.id,
+        session_id=task.session_id,
+        payload={
+            "status": task.status.value,
+            "result": task.result[:500] if task.result else None,
+        },
+    )