agent-yaml 0.1.0__py3-none-any.whl

agent_yaml/__init__.py

@@ -0,0 +1,8 @@
+"""
+agent-yaml: Meta-agent orchestration using declarative YAML workflows.
+
+This package provides a Python CLI tool that orchestrates AI CLI agents
+(Claude, Gemini, Qwen, Codex) using declarative YAML specifications.
+"""
+
+__version__ = "0.1.0"

agent_yaml/adapters/__init__.py

@@ -0,0 +1,95 @@
+"""
+CLI adapter modules for different AI agent tools.
+
+Provides tool-specific adapters that translate generic workflow configurations
+into tool-specific CLI invocations for OpenCode, Claude, Gemini, Qwen, and Codex.
+"""
+
+from .base import BaseAdapter
+from .claude import ClaudeAdapter
+from .codex import CodexAdapter
+from .gemini import GeminiAdapter
+from .opencode import OpenCodeAdapter
+from .qwen import QwenAdapter
+
+
+class UnsupportedCLIError(Exception):
+    """Exception raised when an unsupported or unknown CLI agent is specified."""
+
+    pass
+
+
+class CLINotFoundError(Exception):
+    """Exception raised when the CLI executable is not found in PATH."""
+
+    pass
+
+
+def get_adapter(cli_agent_name: str) -> BaseAdapter:
+    """
+    Factory function to get the appropriate adapter for a CLI agent.
+
+    Args:
+        cli_agent_name: Name of the CLI agent (opencode, claude, gemini, qwen, codex)
+
+    Returns:
+        BaseAdapter: Instance of the appropriate adapter class
+
+    Raises:
+        UnsupportedCLIError: If the CLI agent name is not recognized
+        CLINotFoundError: If the CLI executable is not found in PATH
+
+    Reference:
+        spec/ADAPTER_SPEC.md lines 627-792 for capability detection and translation logic
+    """
+    # Normalize to lowercase for case-insensitive matching
+    cli_name = cli_agent_name.lower().strip()
+
+    # Map CLI agent names to adapter classes
+    adapter_map = {
+        "opencode": OpenCodeAdapter,
+        "claude": ClaudeAdapter,
+        "gemini": GeminiAdapter,
+        "qwen": QwenAdapter,
+        "codex": CodexAdapter,
+    }
+
+    # Check if CLI agent is supported
+    if cli_name not in adapter_map:
+        supported_agents = ", ".join(sorted(adapter_map.keys()))
+        raise UnsupportedCLIError(
+            f"Unsupported CLI agent: '{cli_agent_name}'. Supported agents are: {supported_agents}"
+        )
+
+    # Create adapter instance
+    adapter_class = adapter_map[cli_name]
+    adapter = adapter_class()
+
+    # Validate that CLI executable is available
+    if not adapter.check_available():
+        # Get the expected executable name based on the adapter
+        if cli_name == "claude":
+            executable_hint = "claude-code or claude"
+        else:
+            executable_hint = cli_name
+
+        raise CLINotFoundError(
+            f"CLI executable not found for '{cli_agent_name}'. "
+            f"Please ensure '{executable_hint}' is installed and available in PATH. "
+            f"Run 'which {executable_hint.split()[0]}' to verify installation."
+        )
+
+    return adapter
+
+
+__all__ = [
+    "BaseAdapter",
+    "ClaudeAdapter",
+    "GeminiAdapter",
+    "QwenAdapter",
+    "CodexAdapter",
+    "OpenCodeAdapter",
+    "UnsupportedCLIError",
+    "CLINotFoundError",
+    "get_adapter",
+]

agent_yaml/adapters/base.py

@@ -0,0 +1,55 @@
+"""
+Base adapter abstract class.
+
+Defines the interface that all CLI adapters must implement.
+Provides common functionality for command building and subprocess execution.
+
+All adapters translate generic configurations to tool-specific CLI arguments:
+- skip-confirmations → tool-specific flag
+- additional-dirs → tool-specific workspace/directory flag
+- timeout → subprocess timeout (not CLI arg)
+- mcp-config-file → tool-specific MCP configuration
+
+Reference: spec/ADAPTER_SPEC.md for complete mapping specifications.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class BaseAdapter(ABC):
+    """Abstract base class for CLI adapters."""
+
+    def __init__(self, tool_name, tool_config=None):
+        """
+        Initialize adapter.
+
+        Args:
+            tool_name: Name of the CLI tool (claude, gemini, qwen, codex)
+            tool_config: Optional tool-specific configuration
+        """
+        self.tool_name = tool_name
+        self.tool_config = tool_config or {}
+
+    @abstractmethod
+    def build_command(self, task_config, prompt):
+        """
+        Build CLI command from task configuration.
+
+        Args:
+            task_config: Task configuration dict
+            prompt: Interpolated prompt string
+
+        Returns:
+            list: Command as list of strings (argv format)
+        """
+        pass
+
+    @abstractmethod
+    def check_available(self):
+        """
+        Check if CLI tool is available in PATH.
+
+        Returns:
+            bool: True if tool is available
+        """
+        pass

agent_yaml/adapters/claude.py

@@ -0,0 +1,144 @@
+"""
+Claude CLI adapter.
+
+Maps generic configurations to Claude-specific CLI arguments:
+- skip-confirmations: true → --dangerously-skip-permissions
+- additional-dirs: ["/tmp"] → --add-dir="/tmp"
+- timeout: 3600 → subprocess timeout (not CLI arg)
+- mcp-config-file: "..." → --mcp-config "..."
+- tools: "default" (default) → --tools "default" (enable all tools in print mode)
+- output-format: "stream-json" → --output-format "stream-json" (streaming output)
+
+CLI tool: claude-code or claude (detection via which)
+
+Default behavior: Uses --print mode with tools enabled for non-interactive agentic execution.
+
+Reference: spec/ADAPTER_SPEC.md for complete Claude mappings.
+"""
+
+import shutil
+
+from .base import BaseAdapter
+
+
+class ClaudeAdapter(BaseAdapter):
+    """Adapter for Claude CLI (claude-code)."""
+
+    # Model name translation mapping
+    MODEL_MAPPING = {
+        "sonnet-4.5": "claude-sonnet-4-5-20250929",
+        "opus-4": "claude-opus-4",
+    }
+
+    def __init__(self, tool_config=None):
+        """Initialize Claude adapter."""
+        super().__init__("claude", tool_config)
+
+    def build_command(self, task_config, prompt):
+        """
+        Build Claude CLI command from task configuration.
+
+        Args:
+            task_config: Task configuration dict
+            prompt: Interpolated prompt string
+
+        Returns:
+            list: Command as list of strings (argv format)
+        """
+        # Start with base command - check both "claude" and "claude-code"
+        cmd = []
+        if shutil.which("claude-code"):
+            cmd.append("claude-code")
+        elif shutil.which("claude"):
+            cmd.append("claude")
+        else:
+            cmd.append("claude")  # Default, will fail in check_available
+
+        # Process config options in order per spec
+
+        # 1. skip-confirmations: true → --dangerously-skip-permissions
+        if task_config.get("skip-confirmations"):
+            cmd.append("--dangerously-skip-permissions")
+
+        # 2. additional-dirs: ["/tmp"] → --add-dir="/tmp" (repeat for each)
+        additional_dirs = task_config.get("additional-dirs", [])
+        for directory in additional_dirs:
+            cmd.append(f"--add-dir={directory}")
+
+        # 3. model: "sonnet-4.5" → --model "claude-sonnet-4-5-20250929" (with translation)
+        model = task_config.get("model")
+        if model:
+            # Translate generic model name to Claude-specific identifier
+            translated_model = self.MODEL_MAPPING.get(model, model)
+            cmd.extend(["--model", translated_model])
+
+        # 4. debug: true → --debug
+        if task_config.get("debug"):
+            cmd.append("--debug")
+
+        # 5. tools: "default" → --tools "default" (enable tools in print mode)
+        # Default to "default" which enables all tools for agentic execution
+        tools = task_config.get("tools", "default")
+        if tools:
+            cmd.extend(["--tools", tools])
+
+        # 6. output-format: "stream-json" → --output-format "stream-json"
+        # Default to "text" for simplicity, use "stream-json" in debug mode for streaming
+        output_format = task_config.get("output-format")
+        if output_format is None:
+            # Auto-select: stream-json in debug mode, text otherwise
+            output_format = "stream-json" if task_config.get("debug") else "text"
+
+        # stream-json requires --verbose flag
+        if output_format == "stream-json":
+            cmd.append("--verbose")
+            cmd.extend(["--output-format", "stream-json"])
+        elif output_format != "text":
+            cmd.extend(["--output-format", output_format])
+
+        # 7. session-id: "id" → --session-id "id"
+        session_id = task_config.get("session-id")
+        if session_id:
+            cmd.extend(["--session-id", session_id])
+
+        # 8. mcp-servers: [notion] → --allowed-mcp-server-names notion
+        mcp_servers = task_config.get("mcp-servers", [])
+        if mcp_servers:
+            cmd.append("--allowed-mcp-server-names")
+            cmd.extend(mcp_servers)
+
+        # 9. mcp-config-file: "path" → --mcp-config "path"
+        mcp_config_file = task_config.get("mcp-config-file")
+        if mcp_config_file:
+            cmd.extend(["--mcp-config", mcp_config_file])
+
+        # 10. permissions: ["plan"] → --permission-mode plan
+        permissions = task_config.get("permissions", [])
+        if permissions:
+            # Take first permission mode
+            cmd.extend(["--permission-mode", permissions[0]])
+
+        # 11. raw-args: [...] → append directly at end
+        raw_args = task_config.get("raw-args", [])
+        if raw_args:
+            cmd.extend(raw_args)
+
+        # 12. timeout: 3600 → store but DON'T add to CLI args (used for subprocess timeout)
+        # Note: timeout is handled by executor, not part of CLI command
+
+        # 13. Add prompt in print mode (non-interactive agentic execution)
+        # Always use --print mode with tools enabled for reliable non-interactive execution
+        cmd.extend(["--print", prompt])
+
+        return cmd
+
+    def check_available(self):
+        """
+        Check if Claude CLI is available in PATH.
+
+        Checks for both "claude" and "claude-code" executables.
+
+        Returns:
+            bool: True if tool is available
+        """
+        return shutil.which("claude-code") is not None or shutil.which("claude") is not None

agent_yaml/adapters/codex.py

@@ -0,0 +1,112 @@
+"""
+Codex CLI adapter.
+
+Maps generic configurations to Codex-specific CLI arguments:
+- skip-confirmations: true → --full-auto
+- additional-dirs: ["/tmp"] → -C /tmp (ONLY first directory, warn if multiple)
+- model: pass through as-is (no translation)
+- debug: true → -c debug=true (config style, NOT --debug)
+- permissions: ["on-failure"] → -a on-failure
+- web-search: true → --search
+- PROMPT: DIRECT argument at end (NO flag)
+
+Unsupported features (log warning):
+- output-format
+
+CLI tool: codex exec (uses exec subcommand for non-interactive execution)
+
+Reference: spec/ADAPTER_SPEC.md for complete Codex mappings.
+"""
+
+import logging
+import shutil
+
+from .base import BaseAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class CodexAdapter(BaseAdapter):
+    """Adapter for Codex CLI."""
+
+    def __init__(self, tool_config=None):
+        """Initialize Codex adapter."""
+        super().__init__("codex", tool_config)
+
+    def build_command(self, task_config, prompt):
+        """
+        Build Codex CLI command from task configuration.
+
+        Args:
+            task_config: Task configuration dict
+            prompt: Interpolated prompt string
+
+        Returns:
+            list: Command as list of strings (argv format)
+        """
+        # Start with base command - use 'exec' subcommand for non-interactive execution
+        cmd = ["codex", "exec"]
+
+        # Always add --skip-git-repo-check to allow running in any directory
+        cmd.append("--skip-git-repo-check")
+
+        # Process config options in order per spec
+
+        # 1. skip-confirmations: true → --full-auto
+        if task_config.get("skip-confirmations"):
+            cmd.append("--full-auto")
+
+        # 2. additional-dirs: ["/tmp"] → -C /tmp (ONLY first directory)
+        additional_dirs = task_config.get("additional-dirs", [])
+        if additional_dirs:
+            # Codex only supports one directory
+            cmd.extend(["-C", additional_dirs[0]])
+            if len(additional_dirs) > 1:
+                logger.warning(
+                    f"Codex only supports one directory. Using first directory '{additional_dirs[0]}'. "
+                    f"Additional directories will be ignored: {additional_dirs[1:]}"
+                )
+
+        # 3. model: pass through as-is (no translation)
+        model = task_config.get("model")
+        if model:
+            cmd.extend(["--model", model])
+
+        # 4. debug: true → -c debug=true (config style)
+        if task_config.get("debug"):
+            cmd.extend(["-c", "debug=true"])
+
+        # 5. output-format: NOT SUPPORTED
+        if task_config.get("output-format"):
+            logger.warning("Codex does not support output-format configuration")
+
+        # 6. permissions: ["on-failure"] → -a on-failure
+        permissions = task_config.get("permissions", [])
+        if permissions:
+            # Take first permission mode
+            cmd.extend(["-a", permissions[0]])
+
+        # 7. web-search: true → --search
+        if task_config.get("web-search"):
+            cmd.append("--search")
+
+        # 8. raw-args: passthrough (no translation)
+        raw_args = task_config.get("raw-args", [])
+        if raw_args:
+            cmd.extend(raw_args)
+
+        # 9. Prompt goes at the end as DIRECT argument (NO flag)
+        cmd.append(prompt)
+
+        return cmd
+
+    def check_available(self):
+        """
+        Check if Codex CLI is available in PATH.
+
+        Checks for "codex" executable.
+
+        Returns:
+            bool: True if tool is available
+        """
+        return shutil.which("codex") is not None

agent_yaml/adapters/gemini.py

@@ -0,0 +1,141 @@
+"""
+Gemini CLI adapter.
+
+Maps generic configurations to Gemini-specific CLI arguments:
+- skip-confirmations: true → --yolo or --approval-mode yolo
+- additional-dirs: ["/tmp"] → --include-directories /tmp (space-separated)
+- model: pass through as-is (no translation)
+- permissions: ["plan"] → --approval-mode plan
+- mcp-servers: [notion] → --allowed-mcp-server-names notion
+- extensions: [...] → --extensions ...
+- checkpointing: true → --checkpointing
+- screen-reader: true → --screen-reader
+- telemetry: true → --telemetry
+- web-search: true → BUILT-IN (no flag needed)
+- output-format: "json" → --output-format json
+
+Unsupported features (log warning):
+- session-id
+- mcp-config-file
+
+CLI tool: gemini
+
+Reference: spec/ADAPTER_SPEC.md for complete Gemini mappings.
+"""
+
+import logging
+import shutil
+
+from .base import BaseAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class GeminiAdapter(BaseAdapter):
+    """Adapter for Gemini CLI."""
+
+    def __init__(self, tool_config=None):
+        """Initialize Gemini adapter."""
+        super().__init__("gemini", tool_config)
+
+    def build_command(self, task_config, prompt):
+        """
+        Build Gemini CLI command from task configuration.
+
+        Args:
+            task_config: Task configuration dict
+            prompt: Interpolated prompt string
+
+        Returns:
+            list: Command as list of strings (argv format)
+        """
+        # Start with base command
+        cmd = ["gemini"]
+
+        # Process config options in order per spec
+
+        # 1. skip-confirmations: true → --yolo
+        if task_config.get("skip-confirmations"):
+            cmd.append("--yolo")
+
+        # 2. additional-dirs: ["/tmp"] → --include-directories /tmp (space-separated)
+        additional_dirs = task_config.get("additional-dirs", [])
+        if additional_dirs:
+            cmd.append("--include-directories")
+            cmd.extend(additional_dirs)
+
+        # 3. model: pass through as-is (no translation)
+        model = task_config.get("model")
+        if model:
+            cmd.extend(["--model", model])
+
+        # 4. debug: true → --debug
+        if task_config.get("debug"):
+            cmd.append("--debug")
+
+        # 5. output-format: "json" → --output-format json
+        output_format = task_config.get("output-format")
+        if output_format:
+            cmd.extend(["--output-format", output_format])
+
+        # 6. session-id: NOT SUPPORTED
+        if task_config.get("session-id"):
+            logger.warning("Gemini does not support session-id configuration")
+
+        # 7. mcp-servers: [notion] → --allowed-mcp-server-names notion
+        mcp_servers = task_config.get("mcp-servers", [])
+        if mcp_servers:
+            cmd.append("--allowed-mcp-server-names")
+            cmd.extend(mcp_servers)
+
+        # 8. mcp-config-file: NOT SUPPORTED
+        if task_config.get("mcp-config-file"):
+            logger.warning("Gemini does not support mcp-config-file configuration")
+
+        # 9. permissions: ["plan"] → --approval-mode plan
+        permissions = task_config.get("permissions", [])
+        if permissions:
+            # Take first permission mode
+            cmd.extend(["--approval-mode", permissions[0]])
+
+        # 10. extensions: [...] → --extensions ...
+        extensions = task_config.get("extensions", [])
+        if extensions:
+            cmd.append("--extensions")
+            cmd.extend(extensions)
+
+        # 11. checkpointing: true → --checkpointing
+        if task_config.get("checkpointing"):
+            cmd.append("--checkpointing")
+
+        # 12. telemetry: true → --telemetry
+        if task_config.get("telemetry"):
+            cmd.append("--telemetry")
+
+        # 13. screen-reader: true → --screen-reader
+        if task_config.get("screen-reader"):
+            cmd.append("--screen-reader")
+
+        # 14. web-search: BUILT-IN (no flag needed)
+        # web-search is built-in for Gemini, don't add any flag
+
+        # 15. raw-args: passthrough (no translation)
+        raw_args = task_config.get("raw-args", [])
+        if raw_args:
+            cmd.extend(raw_args)
+
+        # 16. Prompt goes at the end with -p flag
+        cmd.extend(["-p", prompt])
+
+        return cmd
+
+    def check_available(self):
+        """
+        Check if Gemini CLI is available in PATH.
+
+        Checks for "gemini" executable.
+
+        Returns:
+            bool: True if tool is available
+        """
+        return shutil.which("gemini") is not None