coding-agent-cli 0.1.0__py3-none-any.whl

coding_agent_cli/__init__.py

@@ -0,0 +1,47 @@
+"""Run coding-agent CLIs, stream typed events, and return a classified result."""
+
+from .api import EventStream, check, run, run_sync, stream
+from .events import (
+    SCHEMA_VERSION,
+    Event,
+    MessageCompleted,
+    MessageStarted,
+    RunCompleted,
+    SessionIdentified,
+    TextDelta,
+    ToolCompleted,
+    ToolStarted,
+    UsageUpdated,
+)
+from .registry import Driver, DriverRegistry, EventHandler, SpawnHandler
+from .types import Capabilities, Diagnostic, Outcome, Request, Result, Usage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "Capabilities",
+    "Diagnostic",
+    "Driver",
+    "EventStream",
+    "DriverRegistry",
+    "Event",
+    "EventHandler",
+    "MessageCompleted",
+    "MessageStarted",
+    "Outcome",
+    "Request",
+    "Result",
+    "RunCompleted",
+    "SessionIdentified",
+    "SpawnHandler",
+    "TextDelta",
+    "ToolCompleted",
+    "ToolStarted",
+    "Usage",
+    "UsageUpdated",
+    "check",
+    "run",
+    "run_sync",
+    "stream",
+]

coding_agent_cli/_args.py

@@ -0,0 +1,66 @@
+"""Shared validation of raw ``args`` and portable options."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+
+from .types import Diagnostic, Request
+
+PORTABLE_FIELDS = ("model", "reasoning", "system_prompt")
+
+
+def _has_flag(args: Sequence[str], flags: Iterable[str]) -> str | None:
+    """Return the first token in ``args`` that is one of ``flags`` or ``flag=value``."""
+    flag_set = set(flags)
+    for token in args:
+        if token in flag_set or token.split("=", 1)[0] in flag_set:
+            return token
+    return None
+
+
+def validate_args(args: Sequence[Any]) -> Diagnostic | None:
+    """Reject non-string args, NUL bytes, and the reserved bare ``--`` token."""
+    if not all(isinstance(value, str) for value in args):
+        return Diagnostic(code="invalid_args", message="args must contain only strings")
+    if any("\x00" in value for value in args):
+        return Diagnostic(code="invalid_args", message="args cannot contain NUL bytes")
+    if "--" in args:
+        return Diagnostic(code="invalid_args", message="args cannot contain the reserved '--' token")
+    return None
+
+
+def reject_transport_flags(args: Sequence[str], owned: Iterable[str]) -> Diagnostic | None:
+    """Reject a raw arg that overrides a flag the driver owns for transport."""
+    token = _has_flag(args, owned)
+    if token is None:
+        return None
+    return Diagnostic(
+        code="invalid_args", message=f"args cannot override the driver-owned flag {token.split('=', 1)[0]!r}"
+    )
+
+
+def reject_unsupported(req: Request, supported: Iterable[str]) -> Diagnostic | None:
+    """Reject a portable option this driver cannot express."""
+    allowed = set(supported)
+    for name in PORTABLE_FIELDS:
+        if getattr(req, name) is not None and name not in allowed:
+            return Diagnostic(code="unsupported_option", message=f"driver {req.driver!r} does not support {name}")
+    return None
+
+
+def reject_conflicts(req: Request, flags: Mapping[str, Iterable[str]]) -> Diagnostic | None:
+    """Reject a raw arg that sets a portable field already given. ``flags`` maps field to its flags."""
+    for name, field_flags in flags.items():
+        if getattr(req, name) is None:
+            continue
+        token = _has_flag(req.args, field_flags)
+        if token is not None:
+            return Diagnostic(
+                code="invalid_args",
+                message=f"args flag {token.split('=', 1)[0]!r} conflicts with the {name} option",
+            )
+    return None
+
+
+__all__ = ["PORTABLE_FIELDS", "reject_conflicts", "reject_transport_flags", "reject_unsupported", "validate_args"]

coding_agent_cli/_classify.py

@@ -0,0 +1,170 @@
+"""Map facts a driver collected about one run to an ``Outcome`` and ``Diagnostic``.
+
+Rows follow the design's outcome precedence; the first matching row wins.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .types import Diagnostic, Outcome
+
+REQUEST_CODES = frozenset({"bad_cwd", "invalid_args", "unsupported_option", "invalid_prompt"})
+SPAWN_CODES = frozenset({"missing_cli", "spawn_failed"})
+CLI_CODES = ("auth", "invalid_model", "context_overflow", "service_error")
+
+_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "auth": (
+        "authentication",
+        "unauthorized",
+        "forbidden",
+        "api key",
+        "not logged in",
+        "not logged",
+        "login required",
+        "auth_unavailable",
+    ),
+    "invalid_model": ("invalid model", "unknown model", "not a valid model"),
+    "context_overflow": ("context_length_exceeded",),
+    "service_error": (
+        "overloaded",
+        "rate limit",
+        "rate_limit",
+        "too many requests",
+        "internal server error",
+        "service unavailable",
+        "bad gateway",
+    ),
+}
+_CONTEXT_OVERFLOW_RE = re.compile(r"\bcontext_length_exceeded\b")
+
+
+def _normalize(text: str) -> str:
+    return text.lower().replace("node_tls_reject_unauthorized", "")
+
+
+def keyword_code(text: str) -> str:
+    """Return the first CLI code whose keywords appear in ``text``, in precedence order, or ""."""
+    lowered = _normalize(text)
+    if not lowered.strip():
+        return ""
+    for code in CLI_CODES:
+        if code == "context_overflow":
+            if _CONTEXT_OVERFLOW_RE.search(lowered):
+                return code
+        elif any(token in lowered for token in _KEYWORDS[code]):
+            return code
+    return ""
+
+
+def http_status_code(status: int | None) -> str:
+    """Map a CLI-reported HTTP status to a CLI code, or ""."""
+    if status in (401, 403):
+        return "auth"
+    if status == 429 or (status is not None and 500 <= status <= 599):
+        return "service_error"
+    return ""
+
+
+@dataclass(slots=True, kw_only=True)
+class Facts:
+    """What a driver observed. ``cli_error`` is structured CLI error data; ``diagnostics`` is free text."""
+
+    text: str = ""
+    session_id: str | None = None
+    cancelled: bool = False
+    request_error: Diagnostic | None = None
+    process_error: str = ""
+    process_message: str = ""
+    cli_error: Diagnostic | None = None
+    diagnostics: str = ""
+    returncode: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Classification:
+    outcome: Outcome
+    error: Diagnostic | None
+    warnings: tuple[Diagnostic, ...] = ()
+
+
+_CLI_OUTCOMES = {
+    "auth": Outcome.AGENT_FATAL,
+    "invalid_model": Outcome.REQUEST_FATAL,
+    "context_overflow": Outcome.REQUEST_FATAL,
+    "service_error": Outcome.RETRYABLE,
+}
+
+
+def _cli_diagnostic(facts: Facts) -> Diagnostic | None:
+    """Structured CLI error data first, then keyword matching on diagnostics."""
+    if facts.cli_error is not None and facts.cli_error.code in _CLI_OUTCOMES:
+        return facts.cli_error
+    code = keyword_code(facts.diagnostics)
+    if code:
+        return Diagnostic(code=code, message=facts.diagnostics.strip())
+    if facts.cli_error is not None:
+        code = keyword_code(facts.cli_error.message)
+        if code:
+            return Diagnostic(code=code, message=facts.cli_error.message)
+    return None
+
+
+def _message(*parts: str) -> str:
+    return "\n".join(part.strip() for part in parts if part and part.strip())
+
+
+def classify(facts: Facts) -> Classification:
+    # Row 1
+    if facts.cancelled or facts.process_error == "cancelled":
+        return Classification(Outcome.CANCELLED, Diagnostic(code="cancelled", message="run cancelled"))
+    # Rows 2 and 3
+    if facts.request_error is not None:
+        return Classification(Outcome.REQUEST_FATAL, facts.request_error)
+    if facts.process_error in REQUEST_CODES:
+        return Classification(
+            Outcome.REQUEST_FATAL, Diagnostic(code=facts.process_error, message=facts.process_message)
+        )
+    # Row 4
+    if facts.process_error in SPAWN_CODES:
+        return Classification(Outcome.AGENT_FATAL, Diagnostic(code=facts.process_error, message=facts.process_message))
+    # Rows 5 to 7, and 9 after the timeout row
+    cli = _cli_diagnostic(facts)
+    if cli is not None and cli.code != "service_error":
+        return Classification(_CLI_OUTCOMES[cli.code], cli)
+    # Row 8
+    if facts.process_error == "timeout":
+        return Classification(
+            Outcome.RETRYABLE, Diagnostic(code="timeout", message=facts.process_message or "run timed out")
+        )
+    if cli is not None:
+        return Classification(Outcome.RETRYABLE, cli)
+    # Row 10
+    if facts.process_error in {"execution_error", "stdin_failed"}:
+        message = _message(facts.process_message, facts.diagnostics if not facts.text.strip() else "")
+        return Classification(Outcome.RETRYABLE, Diagnostic(code=facts.process_error, message=message))
+    if facts.cli_error is not None:
+        return Classification(Outcome.RETRYABLE, Diagnostic(code="execution_error", message=facts.cli_error.message))
+    if facts.returncode:
+        return Classification(
+            Outcome.RETRYABLE,
+            Diagnostic(
+                code="execution_error",
+                message=_message(f"command exited with status {facts.returncode}", facts.diagnostics),
+            ),
+        )
+    if not facts.text.strip():
+        return Classification(
+            Outcome.RETRYABLE,
+            Diagnostic(code="no_output", message=_message("the CLI produced no assistant text", facts.diagnostics)),
+        )
+    # Row 11
+    if not facts.session_id:
+        return Classification(
+            Outcome.SUCCESS, None, (Diagnostic(code="no_session_id", message="the CLI reported no session ID"),)
+        )
+    return Classification(Outcome.SUCCESS, None)
+
+
+__all__ = ["Classification", "Facts", "classify", "http_status_code", "keyword_code"]

coding_agent_cli/_drivers/__init__.py

@@ -0,0 +1 @@
+"""Built-in drivers. Private: use ``DriverRegistry`` to reach them."""

coding_agent_cli/_drivers/_common.py

@@ -0,0 +1,330 @@
+"""Helpers shared by the built-in drivers: preflight, capability probes, event buffering, and results."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from .._args import reject_conflicts, reject_transport_flags, reject_unsupported, validate_args
+from .._classify import Facts, classify
+from .._process import ProcessOutcome, run_process
+from ..events import Event, ToolStarted
+from ..registry import EventHandler
+from ..types import Capabilities, Diagnostic, Request, Result, Usage
+
+PROBE_TIMEOUT_S = 10.0
+
+_VERIFIED_COMMANDS: dict[str, frozenset[str]] = {
+    "claude": frozenset({"bash"}),
+    "codex": frozenset({"bash"}),
+}
+
+
+def classify_tool_activity(provider: str, tool_name: str) -> Literal["command", "tool_call"]:
+    """Classify tool activity by exact, case-sensitive provider and tool-name allow-lists."""
+    commands = _VERIFIED_COMMANDS.get(provider)
+    if commands is not None and tool_name in commands:
+        return "command"
+    return "tool_call"
+
+
+def tool_started(entity_id: str, provider: str, tool_name: str, tool_input: Any = None) -> ToolStarted:
+    return ToolStarted(
+        entity_id=entity_id,
+        tool=tool_name,
+        activity=classify_tool_activity(provider, tool_name),
+        input=tool_input,
+    )
+
+
+def tool_status(value: Any) -> Literal["completed", "error", "unknown"]:
+    if value in ("completed", "error"):
+        return value
+    if value in ("failed", "failure"):
+        return "error"
+    return "unknown"
+
+
+def parse_json_object(line: str) -> dict[str, Any] | None:
+    """Return the line's JSON object, or None for non-JSON or non-object lines."""
+    try:
+        value = json.loads(line)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def as_int(val: Any) -> int | None:
+    if isinstance(val, bool) or not isinstance(val, int) or val < 0:
+        return None
+    return val
+
+
+def read_and_unlink(path: Path, *, errors: str) -> str:
+    """Return the file's UTF-8 text, or "" when it cannot be read. The file is removed either way."""
+    try:
+        return path.read_text(encoding="utf-8", errors=errors)
+    except OSError:
+        return ""
+    finally:
+        try:
+            path.unlink()
+        except OSError:
+            pass
+
+
+def parse_token_component(usage: dict[str, Any], key: str) -> tuple[int | None, bool]:
+    """Return (value, malformed). A missing or null key is absent, not malformed."""
+    if key not in usage:
+        return None, False
+    val = usage[key]
+    if val is None:
+        return None, False
+    if isinstance(val, bool) or not isinstance(val, int) or val < 0:
+        return None, True
+    return val, False
+
+
+@dataclass(slots=True, frozen=True)
+class TokenUsage:
+    """Normalized usage.
+
+    ``input`` is raw input plus cache reads and writes, or None when the raw input is absent or malformed.
+
+    ``observed`` is True when any component was present or malformed.
+    """
+
+    input: int | None
+    output: int | None
+    cache_read: int | None
+    cache_write: int | None
+    observed: bool
+
+
+NO_USAGE = TokenUsage(input=None, output=None, cache_read=None, cache_write=None, observed=False)
+
+
+def read_usage(
+    usage: dict[str, Any],
+    *,
+    input_key: str = "input_tokens",
+    output_key: str = "output_tokens",
+    cache_read_key: str = "cache_read_input_tokens",
+    cache_write_key: str = "cache_creation_input_tokens",
+) -> TokenUsage:
+    raw_in, raw_in_bad = parse_token_component(usage, input_key)
+    cr, cr_bad = parse_token_component(usage, cache_read_key)
+    cw, cw_bad = parse_token_component(usage, cache_write_key)
+    raw_out, raw_out_bad = parse_token_component(usage, output_key)
+    if raw_in_bad or cr_bad or cw_bad or raw_in is None:
+        norm_in = None
+    else:
+        norm_in = raw_in + (cr or 0) + (cw or 0)
+    observed = any(v is not None for v in (norm_in, cr, cw, raw_out)) or raw_in_bad or cr_bad or cw_bad or raw_out_bad
+    return TokenUsage(input=norm_in, output=raw_out, cache_read=cr, cache_write=cw, observed=observed)
+
+
+class EventBuffer:
+    """Collect the events one parsed line produces, then await the sink once per event in order.
+
+    The parser stays synchronous. ``flush`` runs after each line, so a failing sink fails the run at that line.
+    """
+
+    def __init__(self, sink: EventHandler) -> None:
+        self._sink = sink
+        self._pending: list[Event] = []
+
+    def emit(self, event: Event) -> None:
+        self._pending.append(event)
+
+    async def flush(self) -> None:
+        while self._pending:
+            await self._sink(self._pending.pop(0))
+
+
+class Diagnostics:
+    """Keep the first ``limit`` diagnostic lines, plus the first line that matches ``keep`` beyond it."""
+
+    def __init__(self, limit: int = 50) -> None:
+        self.limit = limit
+        self.lines: list[str] = []
+        self._kept: set[str] = set()
+
+    def add(self, line: str, *, marks: Sequence[str] = ()) -> None:
+        extra = [mark for mark in marks if mark not in self._kept]
+        if len(self.lines) < self.limit or extra:
+            self.lines.append(line)
+            self._kept.update(marks)
+
+    def text(self) -> str:
+        return "\n".join(self.lines).strip()
+
+
+def effective_env(req: Request) -> dict[str, str]:
+    return {**os.environ, **req.env}
+
+
+def resolve_executable(req: Request, default: str) -> Path | None:
+    """Resolve ``req.executable`` or ``default`` on the request's effective ``PATH``."""
+    found = shutil.which(req.executable or default, path=effective_env(req).get("PATH"))
+    return None if found is None else Path(found)
+
+
+def request_failure(req: Request, error: Diagnostic, cancel: asyncio.Event | None = None) -> Result:
+    """A result for a run that never spawned."""
+    verdict = classify(Facts(cancelled=cancel is not None and cancel.is_set(), request_error=error))
+    return Result(outcome=verdict.outcome, session_id=req.session_id, error=verdict.error)
+
+
+def build_result(facts: Facts, *, model: str | None, usage: Usage) -> Result:
+    verdict = classify(facts)
+    return Result(
+        outcome=verdict.outcome,
+        text=facts.text,
+        session_id=facts.session_id or None,
+        model=model,
+        usage=usage,
+        returncode=facts.returncode,
+        error=verdict.error,
+        warnings=verdict.warnings,
+    )
+
+
+def process_facts(process: ProcessOutcome, cancel: asyncio.Event) -> Facts:
+    return Facts(
+        cancelled=cancel.is_set(),
+        process_error=process.error_class,
+        process_message=process.error,
+        returncode=process.returncode,
+    )
+
+
+def deadline_for(req: Request) -> float | None:
+    return None if req.timeout_s is None else time.monotonic() + req.timeout_s
+
+
+class CliDriver:
+    """Shared preflight and capability probe for the built-in drivers.
+
+    Subclasses set ``name``, ``executable``, ``owned_flags``, ``portable_flags`` (supported
+    portable field to the flags that set it), ``help_args``, and ``help_markers``.
+    """
+
+    name = ""
+    executable = ""
+    owned_flags: tuple[str, ...] = ()
+    portable_flags: Mapping[str, tuple[str, ...]] = {}
+    help_args: tuple[str, ...] = ("--help",)
+    help_markers: tuple[str, ...] = ()
+
+    def __init__(self) -> None:
+        self._probe_cache: set[tuple[str, int]] = set()
+        self.log = logging.getLogger(f"coding_agent_cli.drivers.{self.name}")
+
+    def validate(self, req: Request) -> Diagnostic | None:
+        """Driver-specific argument checks. Return a diagnostic to reject the request."""
+        return None
+
+    def preflight(self, req: Request, cancel: asyncio.Event) -> tuple[Path, Path] | Result:
+        """Validate the request and resolve ``(cwd, executable)``, or return the failure result."""
+        error = (
+            validate_args(req.args)
+            or reject_unsupported(req, self.portable_flags)
+            or reject_conflicts(req, self.portable_flags)
+            or reject_transport_flags(req.args, self.owned_flags)
+            or self.validate(req)
+        )
+        cwd = req.cwd.expanduser().absolute()
+        if error is None:
+            if not cwd.is_dir():
+                error = Diagnostic(code="bad_cwd", message=f"cwd {os.fspath(cwd)!r} is not a directory")
+        if error is not None:
+            return request_failure(req, error, cancel)
+        executable = resolve_executable(req, self.executable)
+        if executable is None:
+            name = req.executable or self.executable
+            verdict = classify(
+                Facts(
+                    cancelled=cancel.is_set(),
+                    process_error="missing_cli",
+                    process_message=f"{name!r} was not found on PATH",
+                )
+            )
+            return Result(outcome=verdict.outcome, session_id=req.session_id, error=verdict.error)
+        return cwd, executable
+
+    def portable_argv(self, req: Request) -> list[str]:
+        """Flags for the portable options the request sets, in ``portable_flags`` order."""
+        argv: list[str] = []
+        for name, flags in self.portable_flags.items():
+            value = getattr(req, name)
+            if value is not None:
+                argv.extend([flags[0], value])
+        return argv
+
+    async def check(self, req: Request, *, refresh: bool = False) -> Capabilities:
+        executable = resolve_executable(req, self.executable)
+        if executable is None:
+            return Capabilities(available=False)
+        try:
+            key = (os.fspath(executable), executable.stat().st_mtime_ns)
+        except OSError:
+            return Capabilities(available=False)
+        if not refresh and key in self._probe_cache:
+            return Capabilities(available=True, executable=executable, structured_streaming=True)
+        supported = await self._probe(req, executable)
+        if supported:
+            self._probe_cache.add(key)
+        return Capabilities(available=True, executable=executable, structured_streaming=supported or None)
+
+    async def _probe(self, req: Request, executable: Path) -> bool:
+        lines: list[str] = []
+
+        async def collect(line: str) -> None:
+            lines.append(line)
+
+        try:
+            outcome = await run_process(
+                [os.fspath(executable), *self.help_args],
+                None,
+                dict(req.env),
+                None,
+                time.monotonic() + PROBE_TIMEOUT_S,
+                None,
+                collect,
+            )
+        except OSError:
+            return False
+        if outcome.error_class:
+            return False
+        text = "\n".join(lines)
+        return all(marker in text for marker in self.help_markers)
+
+
+__all__ = [
+    "NO_USAGE",
+    "CliDriver",
+    "Diagnostics",
+    "EventBuffer",
+    "TokenUsage",
+    "as_int",
+    "build_result",
+    "classify_tool_activity",
+    "deadline_for",
+    "effective_env",
+    "parse_json_object",
+    "process_facts",
+    "read_and_unlink",
+    "read_usage",
+    "request_failure",
+    "resolve_executable",
+    "tool_started",
+]

coding_agent_cli/_drivers/_usage.py

@@ -0,0 +1,77 @@
+"""Flat token counters: six nullable integers, null when unknown, never zero-filled."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import Usage
+
+CONSUMPTION_KEYS = ("input", "output", "cache_read", "cache_write")
+
+
+def _count(value: Any) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        return None
+    return value
+
+
+class TokenCounters:
+    """Responses sum across ids; CLI totals and context override them per field."""
+
+    def __init__(self) -> None:
+        self._responses: dict[str, dict[str, int]] = {}
+        self._totals: dict[str, int] = {}
+        self._context: dict[str, int] = {}
+
+    def record_response(
+        self,
+        response_id: str,
+        *,
+        input: Any = None,
+        output: Any = None,
+        cache_read: Any = None,
+        cache_write: Any = None,
+    ) -> None:
+        values = {"input": input, "output": output, "cache_read": cache_read, "cache_write": cache_write}
+        counted = {key: _count(value) for key, value in values.items()}
+        self._responses[response_id] = {key: value for key, value in counted.items() if value is not None}
+
+    def record_totals(
+        self,
+        *,
+        input: Any = None,
+        output: Any = None,
+        cache_read: Any = None,
+        cache_write: Any = None,
+    ) -> None:
+        values = {"input": input, "output": output, "cache_read": cache_read, "cache_write": cache_write}
+        for key, value in values.items():
+            count = _count(value)
+            if count is not None:
+                self._totals[key] = count
+
+    def record_context(self, *, used: Any = None, window: Any = None) -> None:
+        for key, value in (("context_used", used), ("context_window", window)):
+            count = _count(value)
+            if count is not None:
+                self._context[key] = count
+
+    def clear_context(self) -> None:
+        self._context.pop("context_used", None)
+
+    def usage(self) -> Usage:
+        counters: dict[str, int | None] = {}
+        for key in CONSUMPTION_KEYS:
+            if key in self._totals:
+                counters[key] = self._totals[key]
+            else:
+                values = [response[key] for response in self._responses.values() if key in response]
+                counters[key] = sum(values) if values else None
+        return Usage(
+            context_used=self._context.get("context_used"),
+            context_window=self._context.get("context_window"),
+            **counters,
+        )
+
+
+__all__ = ["TokenCounters"]