callai-cli 0.9.0__py3-none-any.whl

callai/__init__.py

@@ -0,0 +1,37 @@
+"""callai: run a prompt non-interactively through any coding-agent harness.
+
+Usage mirrors ``claude -p``::
+
+    callai -n {claude-code,codex,opencode,pi,hermes,grok} -p PROMPT [-m MODEL]
+
+From Python::
+
+    from callai import run
+    result = run("codex", "Fix the failing test", permission="auto")
+    print(result.text, result.session_id)
+
+See ``docs/DESIGN.md`` for the CLI surface and ``conformance/`` for the executable spec.
+"""
+
+from .api import run
+from .cli import main
+from .errors import CallaiError, HarnessNotFound, HarnessTimeout, Interrupted, UsageError
+from .result import Result
+
+__all__ = [
+    "CallaiError",
+    "HarnessNotFound",
+    "HarnessTimeout",
+    "Interrupted",
+    "Result",
+    "UsageError",
+    "main",
+    "run",
+]
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version("callai-cli")  # the distribution name, not the import name
+except metadata.PackageNotFoundError:  # pragma: no cover - running from a source tree that was never installed
+    __version__ = "0.0.0+unknown"

callai/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m callai``: runs :func:`callai.cli.main`."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

callai/adapters/__init__.py

@@ -0,0 +1,82 @@
+"""Harness adapters and the registry that maps ``--name`` values to them."""
+
+from __future__ import annotations
+
+from ..errors import UsageError
+from .base import Adapter, strip_ansi
+
+# Every harness callai supports, in --help order (DESIGN.md §2). Adapters register as they are built.
+HARNESS_NAMES: tuple[str, ...] = ("claude-code", "codex", "opencode", "pi", "hermes", "grok")
+
+REGISTRY: dict[str, Adapter] = {}
+
+
+def register(adapter: Adapter) -> Adapter:
+    """Add an adapter to the registry.
+
+    Args:
+        adapter: The adapter instance; its ``name`` must be one of ``HARNESS_NAMES``.
+
+    Returns:
+        The same adapter, so this can wrap an instantiation.
+
+    Raises:
+        ValueError: If the name is not a supported harness or is already registered.
+    """
+    if adapter.name not in HARNESS_NAMES:
+        raise ValueError(f"{adapter.name!r} is not a supported harness")
+    if adapter.name in REGISTRY:
+        raise ValueError(f"{adapter.name!r} is already registered")
+    REGISTRY[adapter.name] = adapter
+    return adapter
+
+
+def get_adapter(harness_name: str) -> Adapter:
+    """Look up the adapter for a ``--name`` value.
+
+    Args:
+        harness_name: Harness name from the command line, environment or config.
+
+    Returns:
+        The registered adapter.
+
+    Raises:
+        UsageError: If the harness is unknown or its adapter is not implemented yet.
+    """
+    if harness_name not in HARNESS_NAMES:
+        raise UsageError(f"unknown harness {harness_name!r}; choose from {', '.join(HARNESS_NAMES)}")
+    try:
+        return REGISTRY[harness_name]
+    except KeyError:
+        raise UsageError(f"harness {harness_name!r} is not implemented yet") from None
+
+
+# Built-in adapters (imported last: they use register() above).
+from .claude_code import ClaudeCode  # noqa: E402
+from .codex import Codex  # noqa: E402
+from .grok import Grok  # noqa: E402
+from .hermes import Hermes  # noqa: E402
+from .opencode import OpenCode  # noqa: E402
+from .pi import Pi  # noqa: E402
+
+register(ClaudeCode())
+register(Codex())
+register(OpenCode())
+register(Pi())
+register(Grok())
+register(Hermes())
+
+__all__ = [
+    "HARNESS_NAMES",
+    "REGISTRY",
+    "Adapter",
+    "ClaudeCode",
+    "Codex",
+    "Grok",
+    "Hermes",
+    "OpenCode",
+    "Pi",
+    "get_adapter",
+    "register",
+    "strip_ansi",
+]

callai/adapters/base.py

@@ -0,0 +1,190 @@
+"""The interface every harness adapter implements (DESIGN.md §4)."""
+
+from __future__ import annotations
+
+import json
+import re
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..request import Request
+from ..result import Completed, Result
+
+# CSI sequences (colours, cursor moves) and OSC sequences (titles, hyperlinks).
+_ANSI_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape sequences from terminal output.
+
+    Args:
+        text: Text that may contain escape sequences.
+
+    Returns:
+        The text without them.
+    """
+    return _ANSI_RE.sub("", text)
+
+
+def jsonl_events(stdout: str) -> list[dict[str, Any]]:
+    """Parse JSON-lines output, skipping lines that are not JSON objects (banners, warnings).
+
+    Args:
+        stdout: The harness's stdout.
+
+    Returns:
+        The event objects, in order.
+    """
+    return [data for line in stdout.splitlines() if (data := json_line(line)) is not None]
+
+
+def json_line(line: str) -> dict[str, Any] | None:
+    """Parse one line of JSON-lines output.
+
+    Args:
+        line: One stdout line (a trailing newline is fine).
+
+    Returns:
+        The object, or ``None`` if the line isn't a JSON object (a banner, a warning).
+    """
+    try:
+        data = json.loads(line)
+    except ValueError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def content_text(blocks: Any) -> str:
+    """Join the text of a content value: a string, or a list of ``{"type": "text", "text"}`` blocks.
+
+    Args:
+        blocks: A tool result's content.
+
+    Returns:
+        The text; non-text blocks are skipped.
+    """
+    if isinstance(blocks, str):
+        return blocks
+    if not isinstance(blocks, list):
+        return ""
+    return "".join(b["text"] for b in blocks if isinstance(b, dict) and isinstance(b.get("text"), str))
+
+
+def tool_use(call_id: Any, name: Any, tool_input: Any) -> dict[str, Any]:
+    """A normalised ``tool_use`` event (DESIGN.md §5).
+
+    Args:
+        call_id: The harness's id for the call.
+        name: The harness's own tool name.
+        tool_input: The tool's arguments.
+
+    Returns:
+        The event.
+    """
+    return {"type": "tool_use", "id": call_id, "name": name, "input": tool_input}
+
+
+def tool_result(call_id: Any, is_error: bool, output: str) -> dict[str, Any]:
+    """A normalised ``tool_result`` event (DESIGN.md §5).
+
+    Args:
+        call_id: The id of the ``tool_use`` it answers.
+        is_error: Whether the tool failed or was refused.
+        output: What the tool returned, as text.
+
+    Returns:
+        The event.
+    """
+    return {"type": "tool_result", "id": call_id, "is_error": is_error, "output": output}
+
+
+class Adapter(ABC):
+    """Translates a :class:`Request` into one harness's command line and its output back into a :class:`Result`.
+
+    Both methods are pure (no I/O), so adapters are tested without the harness installed.
+
+    Attributes:
+        name: Harness name used with ``--name`` (one of ``callai.adapters.HARNESS_NAMES``).
+        binary: Executable looked up on PATH.
+        install_url: Where to point users when the binary is missing.
+    """
+
+    name: str
+    binary: str
+    install_url: str
+
+    @abstractmethod
+    def build_argv(self, req: Request) -> list[str]:
+        """Build the exact harness command line, with the prompt last after ``--``.
+
+        Args:
+            req: The request to run.
+
+        Returns:
+            The argv list; ``argv[0]`` is the bare binary name.
+        """
+
+    @abstractmethod
+    def parse(self, completed: Completed, req: Request) -> Result:
+        """Turn the harness's raw output into a normalised result.
+
+        Args:
+            completed: Raw process outcome.
+            req: The request that produced it.
+
+        Returns:
+            The normalised result.
+        """
+
+    def build_env(self, req: Request) -> dict[str, str]:
+        """Environment variables the harness needs for this request, set on top of callai's own.
+
+        For settings a harness takes only from its environment (hermes's extra system prompt).
+        Pure, like :meth:`build_argv`.
+
+        Args:
+            req: The request to run.
+
+        Returns:
+            Variables to set; empty (the default) leaves the inherited environment unchanged.
+        """
+        return {}
+
+    def stream_events(self, line: str, state: dict[str, Any]) -> list[dict[str, Any]]:
+        """Map one stdout line of a running harness to normalised ``-o stream-json`` events.
+
+        Called for every stdout line in order, as it arrives, with one ``state`` dict per run for
+        adapters that need to remember earlier lines. Returns ``text``, ``tool_use`` and
+        ``tool_result`` events (DESIGN.md §5); the CLI writes ``start`` and ``result`` itself.
+        Pure apart from ``state``. The default, for harnesses without an event stream, returns none.
+
+        Args:
+            line: One stdout line, newline included.
+            state: Scratch space shared by the calls of one run.
+
+        Returns:
+            The events, possibly none.
+        """
+        return []
+
+    def text_result(self, completed: Completed, req: Request) -> Result:
+        """Fallback parser for harnesses without structured output: cleaned stdout is the answer.
+
+        Args:
+            completed: Raw process outcome.
+            req: The request that produced it.
+
+        Returns:
+            A result whose text is stdout without ANSI codes or surrounding whitespace.
+        """
+        return Result(
+            harness_name=self.name,
+            model=req.model,
+            text=strip_ansi(completed.stdout).strip(),
+            exit_code=completed.exit_code,
+            is_error=completed.exit_code != 0,
+            duration_ms=completed.duration_ms,
+            argv=completed.argv,
+            raw_stdout=completed.stdout,
+            raw_stderr=completed.stderr,
+        )

callai/adapters/claude_code.py

@@ -0,0 +1,194 @@
+"""Adapter for Anthropic's Claude Code CLI (``claude -p``)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..request import Request
+from ..result import Completed, Result
+from .base import Adapter, content_text, json_line, tool_result, tool_use
+
+# callai --permission level -> claude flags (DESIGN.md §7).
+_PERMISSION_FLAGS: dict[str, list[str]] = {
+    "default": [],
+    "read-only": ["--permission-mode", "plan"],
+    "auto": ["--permission-mode", "acceptEdits"],
+    "bypass": ["--dangerously-skip-permissions"],
+}
+
+
+class ClaudeCode(Adapter):
+    """``claude -p --output-format json`` — always asks for JSON so the answer is never scraped from text."""
+
+    name = "claude-code"
+    binary = "claude"
+    install_url = "https://code.claude.com/docs/en/setup"
+
+    def build_argv(self, req: Request) -> list[str]:
+        """Build the ``claude`` command line.
+
+        Args:
+            req: The request to run.
+
+        ``-o stream-json`` asks for claude's own event stream, which needs ``--verbose`` with ``-p``;
+        its last line is the same result object ``--output-format json`` prints.
+
+        Returns:
+            The argv list, prompt last after ``--``.
+        """
+        stream = req.output_format == "stream-json"
+        argv = [self.binary, "-p", "--output-format", *(["stream-json", "--verbose"] if stream else ["json"])]
+        if req.model:
+            argv += ["--model", req.model]
+        argv += _PERMISSION_FLAGS[req.permission]
+        if req.system_prompt is not None:
+            argv += ["--system-prompt", req.system_prompt]
+        return [*argv, *_session_flags(req), *req.extra_args, "--", req.prompt]
+
+    def parse(self, completed: Completed, req: Request) -> Result:
+        """Parse the JSON result object ``claude -p`` prints (alone, or as the last stream-json line).
+
+        Errors come from ``is_error`` or a non-zero exit, never ``subtype`` (claude reports
+        ``"subtype": "success"`` with ``"is_error": true``, e.g. for an unknown model).
+        Output that is not a JSON object falls back to plain text.
+
+        Args:
+            completed: Raw process outcome.
+            req: The request that produced it.
+
+        Returns:
+            The normalised result.
+        """
+        data = _last_json_object(completed.stdout)
+        if data is None:
+            return self.text_result(completed, req).with_updates(is_error=True)
+        is_error = bool(data.get("is_error")) or completed.exit_code != 0
+        text = data.get("result")
+        cost = data.get("total_cost_usd")
+        return Result(
+            harness_name=self.name,
+            model=req.model if is_error else (_main_model(data.get("modelUsage")) or req.model),
+            text=text if isinstance(text, str) else "",
+            exit_code=completed.exit_code,
+            is_error=is_error,
+            duration_ms=completed.duration_ms,
+            session_id=data.get("session_id"),
+            usage=_usage(data.get("usage")),
+            cost_usd=cost if isinstance(cost, int | float) else None,
+            argv=completed.argv,
+            raw_stdout=completed.stdout,
+            raw_stderr=completed.stderr,
+        )
+
+    def stream_events(self, line: str, state: dict[str, Any]) -> list[dict[str, Any]]:
+        """Map a ``--output-format stream-json`` line: assistant text and tool calls, then tool results.
+
+        claude sends whole messages (no ``--include-partial-messages``), so each text event is one
+        complete text block.
+
+        Args:
+            line: One stdout line.
+            state: Unused.
+
+        Returns:
+            The events.
+        """
+        data = json_line(line)
+        message = data.get("message") if data else None
+        if not isinstance(message, dict) or not isinstance(message.get("content"), list):
+            return []
+        events = []
+        for block in message["content"]:
+            if not isinstance(block, dict):
+                continue
+            kind = block.get("type")
+            if data.get("type") == "assistant" and kind == "text":
+                events.append({"type": "text", "text": block.get("text", "")})
+            elif data.get("type") == "assistant" and kind == "tool_use":
+                events.append(tool_use(block.get("id"), block.get("name"), block.get("input")))
+            elif data.get("type") == "user" and kind == "tool_result":
+                events.append(
+                    tool_result(
+                        block.get("tool_use_id"), bool(block.get("is_error")), content_text(block.get("content"))
+                    )
+                )
+        return events
+
+
+def _last_json_object(stdout: str) -> dict[str, Any] | None:
+    """Find the result object: the whole output, else the last line that is a JSON object.
+
+    Args:
+        stdout: The harness's stdout.
+
+    Returns:
+        The parsed object, or ``None`` if there is none.
+    """
+    for candidate in (stdout, *reversed(stdout.splitlines())):
+        try:
+            data = json.loads(candidate)
+        except ValueError:
+            continue
+        if isinstance(data, dict):
+            return data
+    return None
+
+
+def _usage(raw: Any) -> dict[str, int] | None:
+    """Normalise claude's usage: input counts cache reads and writes too (conformance/README.md).
+
+    Args:
+        raw: claude's ``usage`` value.
+
+    Returns:
+        ``{"input_tokens", "output_tokens"}``, or ``None`` if absent.
+    """
+    if not isinstance(raw, dict):
+        return None
+    keys = ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens")
+    return {
+        "input_tokens": sum(int(raw.get(k) or 0) for k in keys),
+        "output_tokens": int(raw.get("output_tokens") or 0),
+    }
+
+
+def _main_model(model_usage: Any) -> str | None:
+    """Pick the model that did the work from ``modelUsage`` (claude also lists side-call models).
+
+    Args:
+        model_usage: claude's ``modelUsage`` mapping of model id to stats.
+
+    Returns:
+        The model with the highest cost (then output tokens), or ``None``.
+    """
+    if not isinstance(model_usage, dict) or not model_usage:
+        return None
+
+    def weight(item: tuple[str, Any]) -> tuple[float, float]:
+        """Sort key: (cost, output tokens).
+
+        Args:
+            item: A ``(model id, stats)`` pair.
+
+        Returns:
+            The key.
+        """
+        stats = item[1] if isinstance(item[1], dict) else {}
+        return (float(stats.get("costUSD") or 0), float(stats.get("outputTokens") or 0))
+
+    return max(model_usage.items(), key=weight)[0]
+
+
+def _session_flags(req: Request) -> list[str]:
+    """The harness's flags for ``--resume ID`` / ``--continue`` (none for a new session).
+
+    Args:
+        req: The request.
+
+    Returns:
+        The flags.
+    """
+    if req.resume is not None:
+        return ["--resume", req.resume]
+    return ["--continue"] if req.continue_session else []

callai/adapters/codex.py

@@ -0,0 +1,155 @@
+"""Adapter for OpenAI's Codex CLI (``codex exec``)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..request import Request
+from ..result import Completed, Result
+from .base import Adapter, json_line, jsonl_events, tool_result, tool_use
+
+# callai --permission level -> codex flags (DESIGN.md §7; verified against codex-cli 0.166.0 --help).
+_PERMISSION_FLAGS: dict[str, list[str]] = {
+    "default": [],
+    "read-only": ["--sandbox", "read-only"],
+    "auto": ["--sandbox", "workspace-write"],
+    "bypass": ["--dangerously-bypass-approvals-and-sandbox"],
+}
+
+
+# Item types that are not tool calls; every other item type (command_execution, file_change,
+# mcp_tool_call, web_search, ...) is reported as a tool call named after its type.
+_NOT_TOOLS = {"agent_message", "reasoning", "error", "todo_list"}
+# Item fields that describe the call's outcome rather than its input.
+_OUTCOME_KEYS = {"id", "type", "status", "aggregated_output", "exit_code", "result", "error"}
+
+
+def toml_string(text: str) -> str:
+    """Encode text as a TOML basic string (for codex ``-c key=value`` overrides).
+
+    JSON string escapes are valid TOML, except that TOML also forbids a raw DEL character.
+
+    Args:
+        text: Any text.
+
+    Returns:
+        The quoted TOML string.
+    """
+    return json.dumps(text, ensure_ascii=False).replace("\x7f", "\\u007f")
+
+
+class Codex(Adapter):
+    """``codex exec --json`` — parses the JSONL event stream rather than scraping text."""
+
+    name = "codex"
+    binary = "codex"
+    install_url = "https://developers.openai.com/codex/cli"
+
+    def build_argv(self, req: Request) -> list[str]:
+        """Build the ``codex exec`` command line.
+
+        ``--skip-git-repo-check`` is always added, so callai works in any directory like the other tools.
+
+        Args:
+            req: The request to run.
+
+        Returns:
+            The argv list, prompt last after ``--`` (so it can't be taken for a subcommand like ``review``).
+        """
+        argv = [self.binary, "exec", "--json", "--skip-git-repo-check"]
+        if req.model:
+            argv += ["--model", req.model]
+        argv += _PERMISSION_FLAGS[req.permission]
+        if req.system_prompt is not None:
+            argv += ["-c", f"developer_instructions={toml_string(req.system_prompt)}"]
+        # `resume` is a subcommand of exec that rejects --sandbox, so exec's own options (and any extra
+        # args) go before it; only the session id or --last follow it.
+        if req.resume is not None:
+            resume = ["resume", req.resume]
+        else:
+            resume = ["resume", "--last"] if req.continue_session else []
+        return [*argv, *req.extra_args, *resume, "--", req.prompt]
+
+    def parse(self, completed: Completed, req: Request) -> Result:
+        """Parse the JSONL events of ``codex exec --json``.
+
+        The answer is the last ``agent_message`` item. Failure comes only from ``turn.failed`` or a
+        non-zero exit: ``error`` events and ``item.type == "error"`` items are non-fatal warnings
+        (reconnects, missing model metadata). codex does not report the model it used.
+
+        Args:
+            completed: Raw process outcome.
+            req: The request that produced it.
+
+        Returns:
+            The normalised result.
+        """
+        events = jsonl_events(completed.stdout)
+        if not events:
+            return self.text_result(completed, req).with_updates(is_error=True)
+        text, session_id, usage, failure = "", None, None, None
+        for ev in events:
+            kind = ev.get("type")
+            if kind == "thread.started":
+                session_id = ev.get("thread_id")
+            elif kind == "item.completed":
+                item = ev.get("item") or {}
+                if item.get("type") == "agent_message" and isinstance(item.get("text"), str):
+                    text = item["text"]
+            elif kind == "turn.completed" and isinstance(ev.get("usage"), dict):
+                usage = {
+                    # OpenAI semantics: input_tokens already includes cached_input_tokens.
+                    "input_tokens": int(ev["usage"].get("input_tokens") or 0),
+                    "output_tokens": int(ev["usage"].get("output_tokens") or 0),
+                }
+            elif kind == "turn.failed":
+                failure = (ev.get("error") or {}).get("message") or text
+        return Result(
+            harness_name=self.name,
+            model=req.model,
+            text=failure if failure is not None else text,
+            exit_code=completed.exit_code,
+            is_error=failure is not None or completed.exit_code != 0,
+            duration_ms=completed.duration_ms,
+            session_id=session_id,
+            usage=usage,
+            argv=completed.argv,
+            raw_stdout=completed.stdout,
+            raw_stderr=completed.stderr,
+        )
+
+    def stream_events(self, line: str, state: dict[str, Any]) -> list[dict[str, Any]]:
+        """Map a ``codex exec --json`` line: ``agent_message`` items are text, other items tool calls.
+
+        A tool call is reported when its item starts (``item.started``) and its result when the item
+        completes. Items that only arrive completed get both then; ``state`` remembers which calls
+        were already reported. Verified for ``command_execution``; other item types follow the same
+        event schema (their fields, minus outcome fields, become the input).
+
+        Args:
+            line: One stdout line.
+            state: Remembers reported call ids (``"started"``).
+
+        Returns:
+            The events.
+        """
+        data = json_line(line)
+        item = data.get("item") if data else None
+        if not isinstance(item, dict):
+            return []
+        kind, item_id = item.get("type"), item.get("id")
+        if data.get("type") == "item.completed" and kind == "agent_message":
+            return [{"type": "text", "text": item.get("text", "")}]
+        if kind in _NOT_TOOLS or data.get("type") not in ("item.started", "item.completed"):
+            return []
+        started = state.setdefault("started", set())
+        events = []
+        if item_id not in started:
+            started.add(item_id)
+            events.append(tool_use(item_id, kind, {k: v for k, v in item.items() if k not in _OUTCOME_KEYS}))
+        if data["type"] == "item.completed":
+            failed = item.get("status") == "failed" or item.get("exit_code") not in (None, 0) or bool(item.get("error"))
+            output = item.get("aggregated_output")
+            events.append(tool_result(item_id, failed, output if isinstance(output, str) else ""))
+        return events