cacli 0.1.0__py3-none-any.whl

cacli/__init__.py

@@ -0,0 +1,28 @@
+"""
+cacli — Coding Agent CLI.
+
+Provider-agnostic interface for running headless coding agents.
+"""
+
+from cacli.providers import get_provider, list_providers
+from cacli.runner import (
+    build_command,
+    build_initial_log_entry,
+    parse_output,
+    run_agent,
+)
+from cacli.sessions import SessionInfo
+from cacli.types import AgentRunResult, ExecResult, ShellExecFn
+
+__all__ = [
+    "run_agent",
+    "build_command",
+    "parse_output",
+    "build_initial_log_entry",
+    "get_provider",
+    "list_providers",
+    "AgentRunResult",
+    "ExecResult",
+    "ShellExecFn",
+    "SessionInfo",
+]

cacli/cli.py

@@ -0,0 +1,195 @@
+"""CLI entrypoint for cacli."""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+from cacli.providers import list_providers
+from cacli.runner import build_command, run_agent
+from cacli.types import ExecResult
+
+
+def subprocess_exec(
+    cmd: str, cwd: str, timeout: int, env: dict[str, str] | None
+) -> ExecResult:
+    """Default exec_fn using subprocess."""
+    full_env = os.environ.copy()
+    if env:
+        full_env.update(env)
+    try:
+        result = subprocess.run(
+            cmd,
+            shell=True,
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=timeout,
+            env=full_env,
+        )
+        return ExecResult(
+            exit_code=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+        )
+    except subprocess.TimeoutExpired:
+        return ExecResult(exit_code=124, stdout="", stderr="Command timed out")
+
+
+def _normalize_argv(argv: list[str]) -> list[str]:
+    """Prepend 'run' if first arg isn't a known subcommand.
+
+    Preserves backward compat: ``cacli "my prompt"`` works as ``cacli run "my prompt"``.
+    """
+    if not argv:
+        return argv
+    first = argv[0]
+    known = {"run", "spawn", "status"}
+    if first in known or first in ("-h", "--help", "help") or first.startswith("-"):
+        return argv
+    return ["run", *argv]
+
+
+def _add_common_args(parser: argparse.ArgumentParser) -> None:
+    """Add arguments shared between run and spawn."""
+    parser.add_argument("prompt", help="The task prompt")
+    parser.add_argument(
+        "--provider",
+        "-p",
+        default="claude",
+        choices=list_providers(),
+        help="Agent provider (default: claude)",
+    )
+    parser.add_argument("--model", "-m", default=None, help="Model name")
+    parser.add_argument("--reasoning-effort", "-e", default=None)
+    parser.add_argument(
+        "--settings",
+        "-s",
+        default=None,
+        help="Path to settings file (forwarded to claude --settings)",
+    )
+    parser.add_argument(
+        "--no-web-search",
+        dest="web_search",
+        action="store_false",
+        default=True,
+    )
+    parser.add_argument("--cwd", default=".", help="Working directory")
+    parser.add_argument(
+        "--timeout", "-t", type=int, default=3600, help="Timeout in seconds"
+    )
+
+
+def _run_command(args) -> None:
+    """Handle 'cacli run' — synchronous agent execution."""
+    if args.command_only:
+        cmd = build_command(
+            args.provider,
+            args.prompt,
+            model=args.model,
+            reasoning_effort=args.reasoning_effort,
+            web_search=args.web_search,
+            settings=args.settings,
+        )
+        print(cmd)
+        return
+
+    result = run_agent(
+        provider=args.provider,
+        prompt=args.prompt,
+        exec_fn=subprocess_exec,
+        model=args.model,
+        reasoning_effort=args.reasoning_effort,
+        web_search=args.web_search,
+        settings=args.settings,
+        cwd=args.cwd,
+        timeout=args.timeout,
+    )
+
+    if args.raw:
+        print(result.raw_output)
+    elif args.json:
+        print(
+            json.dumps(
+                {
+                    "exit_code": result.exit_code,
+                    "result_message": result.result_message,
+                    "total_cost": result.total_cost,
+                    "provider": result.provider,
+                    "model": result.model,
+                    "command": result.command,
+                },
+                indent=2,
+            )
+        )
+    else:
+        if result.result_message:
+            print(result.result_message)
+        else:
+            print(result.raw_output)
+
+    sys.exit(result.exit_code)
+
+
+def _spawn_command(args) -> None:
+    """Handle 'cacli spawn' — launch agent in tmux."""
+    from cacli.spawn import spawn_agent
+
+    spawn_agent(args)
+
+
+def _status_command(_args) -> None:
+    """Handle 'cacli status' — TUI dashboard."""
+    from cacli.status import status_tui
+
+    status_tui()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="cacli",
+        description="Run coding agents (provider-agnostic)",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # cacli run <prompt>
+    run_parser = subparsers.add_parser("run", help="Run agent synchronously")
+    _add_common_args(run_parser)
+    run_parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="Print raw output instead of parsed result",
+    )
+    run_parser.add_argument(
+        "--command-only",
+        action="store_true",
+        help="Just print the command, don't execute",
+    )
+    run_parser.add_argument("--json", action="store_true", help="Output result as JSON")
+
+    # cacli spawn <prompt>
+    spawn_parser = subparsers.add_parser("spawn", help="Spawn agent in tmux session")
+    _add_common_args(spawn_parser)
+    spawn_parser.add_argument(
+        "--name", "-n", default=None, help="Human-readable session name"
+    )
+
+    # cacli status
+    subparsers.add_parser("status", help="Show spawned agent dashboard")
+
+    args = parser.parse_args(_normalize_argv(sys.argv[1:]))
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+    elif args.command == "run":
+        _run_command(args)
+    elif args.command == "spawn":
+        _spawn_command(args)
+    elif args.command == "status":
+        _status_command(args)
+
+
+if __name__ == "__main__":
+    main()

cacli/providers/__init__.py

@@ -0,0 +1,33 @@
+"""Provider registry."""
+
+from cacli.providers.base import BaseProvider
+from cacli.providers.claude import ClaudeProvider
+from cacli.providers.codex import CodexProvider
+from cacli.providers.cursor import CursorProvider
+from cacli.providers.gemini import GeminiProvider
+
+_PROVIDERS: dict[str, BaseProvider] = {}
+
+
+def _init_registry() -> None:
+    _PROVIDERS["claude"] = ClaudeProvider()
+    _PROVIDERS["codex"] = CodexProvider()
+    _PROVIDERS["openai"] = CodexProvider()
+    _PROVIDERS["gemini"] = GeminiProvider()
+    _PROVIDERS["cursor"] = CursorProvider()
+
+
+_init_registry()
+
+
+def get_provider(name: str) -> BaseProvider:
+    """Get a provider instance by name."""
+    if name not in _PROVIDERS:
+        available = ", ".join(sorted(_PROVIDERS))
+        raise ValueError(f"Unknown provider: {name}. Available: {available}")
+    return _PROVIDERS[name]
+
+
+def list_providers() -> list[str]:
+    """List all available provider names."""
+    return sorted(_PROVIDERS.keys())

cacli/providers/base.py

@@ -0,0 +1,52 @@
+"""Abstract base class for coding agent providers."""
+
+from abc import ABC, abstractmethod
+
+from cacli.types import AgentRunResult
+
+
+class BaseProvider(ABC):
+    """Abstract base for all coding agent providers."""
+
+    name: str
+
+    @abstractmethod
+    def build_command(
+        self,
+        prompt: str,
+        model: str | None = None,
+        reasoning_effort: str | None = None,
+        web_search: bool = True,
+        settings: str | None = None,
+    ) -> str:
+        """Build the shell command string to invoke this provider."""
+        ...
+
+    @abstractmethod
+    def parse_output(self, raw_output: str) -> AgentRunResult:
+        """Parse raw output and extract result message, cost, etc."""
+        ...
+
+    @abstractmethod
+    def build_initial_log_entry(self, prompt: str, model: str | None = None) -> str:
+        """Build the initial JSONL log entry for this provider's format."""
+        ...
+
+    @abstractmethod
+    def build_pr_description_command(
+        self,
+        prompt: str,
+        model: str | None = None,
+        settings: str | None = None,
+    ) -> str:
+        """Build command for generating PR descriptions."""
+        ...
+
+    @abstractmethod
+    def extract_result_from_json(self, raw_output: str) -> str:
+        """Extract the result text from JSON output."""
+        ...
+
+    def resolve_model(self, model: str | None) -> str | None:
+        """Resolve model aliases. Override in providers with aliases."""
+        return model

cacli/providers/claude.py

@@ -0,0 +1,129 @@
+"""Claude Code provider."""
+
+import json
+import shlex
+
+from cacli.providers.base import BaseProvider
+from cacli.types import AgentRunResult
+
+
+class ClaudeProvider(BaseProvider):
+    """Provider for the Claude Code CLI."""
+
+    name = "claude"
+
+    def build_command(
+        self,
+        prompt: str,
+        model: str | None = None,
+        reasoning_effort: str | None = None,
+        web_search: bool = True,
+        settings: str | None = None,
+    ) -> str:
+        safe_prompt = shlex.quote(prompt)
+        cmd = f"claude -p {safe_prompt} --verbose --output-format=stream-json"
+        if model:
+            cmd += f" --model {shlex.quote(model)}"
+        if settings:
+            cmd += f" --settings {shlex.quote(settings)}"
+        if not web_search:
+            cmd += " --disallowedTools WebFetch --disallowedTools WebSearch"
+        return cmd
+
+    def parse_output(self, raw_output: str) -> AgentRunResult:
+        result_message = ""
+        total_cost = None
+        permission_denials = []
+
+        for line in reversed(raw_output.strip().split("\n")):
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+                entries = entry if isinstance(entry, list) else [entry]
+                for item in reversed(entries):
+                    if not isinstance(item, dict):
+                        continue
+                    if item.get("type") == "result":
+                        result_message = item.get("result", "")
+                        total_cost = item.get("total_cost_usd")
+                        permission_denials = item.get("permission_denials", [])
+                        break
+                if result_message:
+                    break
+            except json.JSONDecodeError:
+                continue
+
+        return AgentRunResult(
+            result_message=result_message,
+            total_cost=total_cost,
+            permission_denials=permission_denials,
+        )
+
+    def build_initial_log_entry(self, prompt: str, model: str | None = None) -> str:
+        return json.dumps(
+            {
+                "type": "user",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": prompt}],
+                },
+            }
+        )
+
+    def build_pr_description_command(
+        self,
+        prompt: str,
+        model: str | None = None,
+        settings: str | None = None,
+    ) -> str:
+        safe_prompt = shlex.quote(prompt)
+        cmd = f"claude -p {safe_prompt} --verbose --output-format json"
+        if model:
+            cmd += f" --model {shlex.quote(model)}"
+        if settings:
+            cmd += f" --settings {shlex.quote(settings)}"
+        return cmd
+
+    def extract_result_from_json(self, raw_output: str) -> str:
+        # First try single-object JSON with "result" key
+        try:
+            data = json.loads(raw_output)
+            if isinstance(data, dict) and "result" in data:
+                return data["result"]
+            if isinstance(data, list):
+                for item in reversed(data):
+                    if isinstance(item, dict) and "result" in item:
+                        return item["result"]
+        except json.JSONDecodeError:
+            pass
+
+        # Try JSONL: extract result from stream-json format
+        # (same logic as parse_output)
+        for line in reversed(raw_output.strip().split("\n")):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+                entries = entry if isinstance(entry, list) else [entry]
+                for item in reversed(entries):
+                    if not isinstance(item, dict):
+                        continue
+                    if item.get("type") == "result":
+                        return item.get("result", "")
+            except json.JSONDecodeError:
+                continue
+
+        # Fallback: look for any line with "result" key
+        for line in raw_output.split("\n"):
+            line = line.strip()
+            if line.startswith("{") and "result" in line:
+                try:
+                    data = json.loads(line)
+                    if isinstance(data, dict) and "result" in data:
+                        return data["result"]
+                except json.JSONDecodeError:
+                    continue
+
+        return raw_output

cacli/providers/codex.py

@@ -0,0 +1,111 @@
+"""Codex/OpenAI provider."""
+
+import json
+import shlex
+
+from cacli.providers.base import BaseProvider
+from cacli.types import AgentRunResult
+
+
+class CodexProvider(BaseProvider):
+    """Provider for Codex/OpenAI CLI."""
+
+    name = "codex"
+
+    def build_command(
+        self,
+        prompt: str,
+        model: str | None = None,
+        reasoning_effort: str | None = None,
+        web_search: bool = True,
+        settings: str | None = None,
+    ) -> str:
+        safe_prompt = shlex.quote(prompt)
+        cmd = f"codex exec {safe_prompt} --sandbox danger-full-access --json --skip-git-repo-check"
+        if model:
+            cmd += f" --model {shlex.quote(model)}"
+        if reasoning_effort is not None:
+            cmd += f" --config model_reasoning_effort={reasoning_effort}"
+        if web_search:
+            cmd += " --config features.web_search_request=true"
+        return cmd
+
+    def parse_output(self, raw_output: str) -> AgentRunResult:
+        result_message = ""
+
+        for line in reversed(raw_output.strip().split("\n")):
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+                if entry.get("type") == "item.completed":
+                    item = entry.get("item", {})
+                    if item.get("type") == "agent_message":
+                        result_message = item.get("text", "")
+                        break
+            except json.JSONDecodeError:
+                continue
+
+        return AgentRunResult(result_message=result_message)
+
+    def build_initial_log_entry(self, prompt: str, model: str | None = None) -> str:
+        item = {
+            "id": "item_user",
+            "type": "user_message",
+            "text": prompt,
+        }
+        if model:
+            item["model"] = model
+        return json.dumps({"type": "item.completed", "item": item})
+
+    def build_pr_description_command(
+        self,
+        prompt: str,
+        model: str | None = None,
+        settings: str | None = None,
+    ) -> str:
+        safe_prompt = shlex.quote(prompt)
+        cmd = f"codex exec {safe_prompt} --sandbox danger-full-access --json --skip-git-repo-check"
+        if model:
+            cmd += f" --model {shlex.quote(model)}"
+        return cmd
+
+    def extract_result_from_json(self, raw_output: str) -> str:
+        # First try single-object JSON with "result" key
+        try:
+            data = json.loads(raw_output)
+            if isinstance(data, dict) and "result" in data:
+                return data["result"]
+        except json.JSONDecodeError:
+            pass
+
+        # Try JSONL: extract last agent_message from item.completed events
+        # (same logic as parse_output)
+        for line in reversed(raw_output.strip().split("\n")):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+                if entry.get("type") == "item.completed":
+                    item = entry.get("item", {})
+                    if item.get("type") == "agent_message":
+                        return item.get("text", "")
+            except json.JSONDecodeError:
+                continue
+
+        # Fallback: look for any line with "result" key
+        for line in raw_output.split("\n"):
+            line = line.strip()
+            if line.startswith("{") and "result" in line:
+                try:
+                    data = json.loads(line)
+                    if "result" in data:
+                        return data["result"]
+                except json.JSONDecodeError:
+                    continue
+
+        return raw_output
+
+    def skills_dir(self) -> str:
+        return "/root/.codex/skills"

cacli/providers/cursor.py

@@ -0,0 +1,140 @@
+"""Cursor provider."""
+
+import json
+import shlex
+
+from cacli.providers.base import BaseProvider
+from cacli.types import AgentRunResult
+
+CURSOR_DEFAULT_MODEL = "composer-1"
+
+CURSOR_ALLOWED_MODELS = {
+    "composer-1",
+    "gpt-5.2-codex",
+    "gpt-5.1-codex-max",
+    "gpt-5.1-codex-max-high",
+    "gpt-5.2",
+    "gpt-5.2-high",
+    "gpt-5.1-high",
+    "opus-4.5-thinking",
+    "opus-4.5",
+    "sonnet-4.5",
+    "sonnet-4.5-thinking",
+    "gemini-3-pro",
+    "gemini-3-flash",
+    "grok",
+}
+
+
+class CursorProvider(BaseProvider):
+    """Provider for Cursor Agent CLI."""
+
+    name = "cursor"
+
+    def resolve_model(self, model: str | None) -> str:
+        if not model:
+            return CURSOR_DEFAULT_MODEL
+        if model not in CURSOR_ALLOWED_MODELS:
+            allowed = ", ".join(sorted(CURSOR_ALLOWED_MODELS))
+            raise ValueError(f"Unsupported cursor model '{model}'. Allowed: {allowed}")
+        return model
+
+    def build_command(
+        self,
+        prompt: str,
+        model: str | None = None,
+        reasoning_effort: str | None = None,
+        web_search: bool = True,
+        settings: str | None = None,
+    ) -> str:
+        resolved_model = self.resolve_model(model)
+        safe_prompt = shlex.quote(prompt)
+        cmd = f"agent --print --output-format stream-json --force --model {shlex.quote(resolved_model)} {safe_prompt}"
+        return cmd
+
+    def parse_output(self, raw_output: str) -> AgentRunResult:
+        result_message = ""
+
+        for line in reversed(raw_output.strip().split("\n")):
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+                if entry.get("type") == "assistant":
+                    message = entry.get("message", {})
+                    content = message.get("content", [])
+                    if isinstance(content, list) and content:
+                        text = content[0].get("text")
+                        if text:
+                            result_message = text
+                            break
+            except json.JSONDecodeError:
+                continue
+
+        return AgentRunResult(result_message=result_message)
+
+    def build_initial_log_entry(self, prompt: str, model: str | None = None) -> str:
+        # Cursor uses the same format as Claude for initial log entries
+        return json.dumps(
+            {
+                "type": "user",
+                "message": {
+                    "role": "user",
+                    "content": [{"type": "text", "text": prompt}],
+                },
+            }
+        )
+
+    def build_pr_description_command(
+        self,
+        prompt: str,
+        model: str | None = None,
+        settings: str | None = None,
+    ) -> str:
+        resolved_model = self.resolve_model(model)
+        safe_prompt = shlex.quote(prompt)
+        cmd = f"agent --print --output-format json --force --model {shlex.quote(resolved_model)} {safe_prompt}"
+        return cmd
+
+    def extract_result_from_json(self, raw_output: str) -> str:
+        # First try single-object JSON with "result" key
+        try:
+            data = json.loads(raw_output)
+            if isinstance(data, dict) and "result" in data:
+                return data["result"]
+        except json.JSONDecodeError:
+            pass
+
+        # Try JSONL: extract last assistant message from stream-json format
+        # (same logic as parse_output)
+        for line in reversed(raw_output.strip().split("\n")):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+                if entry.get("type") == "assistant":
+                    message = entry.get("message", {})
+                    content = message.get("content", [])
+                    if isinstance(content, list) and content:
+                        text = content[0].get("text")
+                        if text:
+                            return text
+            except json.JSONDecodeError:
+                continue
+
+        # Fallback: look for any line with "result" key
+        for line in raw_output.split("\n"):
+            line = line.strip()
+            if line.startswith("{") and "result" in line:
+                try:
+                    data = json.loads(line)
+                    if "result" in data:
+                        return data["result"]
+                except json.JSONDecodeError:
+                    continue
+
+        return raw_output
+
+    def skills_dir(self) -> str:
+        return "/root/.cursor/skills"