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

coding_agent_cli/__init__.py

@@ -1,11 +1,17 @@
 """Run coding-agent CLIs, stream typed events, and return a classified result."""
 
 from .api import EventStream, check, run, run_sync, stream
+from .driver import CliDriver, Facts, Launch, Parser, RequestError
 from .events import (
     SCHEMA_VERSION,
     Event,
+    FileChanged,
+    JsonValue,
     MessageCompleted,
     MessageStarted,
+    Notice,
+    RawEvent,
+    ReasoningDelta,
     RunCompleted,
     SessionIdentified,
     TextDelta,
@@ -13,28 +19,36 @@ from .events import (
     ToolStarted,
     UsageUpdated,
 )
-from .registry import Driver, DriverRegistry, EventHandler, SpawnHandler
-from .types import Capabilities, Diagnostic, Outcome, Request, Result, Usage
+from .registry import DriverRegistry
+from .types import Capabilities, Diagnostic, ErrorCode, Outcome, Request, Result, Usage
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "SCHEMA_VERSION",
     "Capabilities",
     "Diagnostic",
-    "Driver",
-    "EventStream",
+    "CliDriver",
     "DriverRegistry",
+    "ErrorCode",
     "Event",
-    "EventHandler",
+    "EventStream",
+    "FileChanged",
+    "Facts",
+    "JsonValue",
     "MessageCompleted",
     "MessageStarted",
+    "Launch",
+    "Notice",
     "Outcome",
+    "RawEvent",
+    "ReasoningDelta",
     "Request",
     "Result",
     "RunCompleted",
     "SessionIdentified",
-    "SpawnHandler",
+    "Parser",
+    "RequestError",
     "TextDelta",
     "ToolCompleted",
     "ToolStarted",

coding_agent_cli/_args.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from collections.abc import Iterable, Mapping, Sequence
 from typing import Any
 
-from .types import Diagnostic, Request
+from .types import Diagnostic, ErrorCode, Request
 
 PORTABLE_FIELDS = ("model", "reasoning", "system_prompt")
 
@@ -22,11 +22,21 @@ def _has_flag(args: Sequence[str], flags: Iterable[str]) -> str | 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")
+        return Diagnostic(code=ErrorCode.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")
+        return Diagnostic(code=ErrorCode.INVALID_ARGS, message="args cannot contain NUL bytes")
     if "--" in args:
-        return Diagnostic(code="invalid_args", message="args cannot contain the reserved '--' token")
+        return Diagnostic(code=ErrorCode.INVALID_ARGS, message="args cannot contain the reserved '--' token")
+    return None
+
+
+def validate_request(req: Request) -> Diagnostic | None:
+    """Validate the request fields that are common to every CLI driver."""
+    error = validate_args(req.args)
+    if error is not None:
+        return error
+    if not req.cwd.is_dir():
+        return Diagnostic(code=ErrorCode.BAD_CWD, message="cwd is not an existing directory")
     return None
 
 
@@ -36,7 +46,8 @@ def reject_transport_flags(args: Sequence[str], owned: Iterable[str]) -> Diagnos
     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}"
+        code=ErrorCode.INVALID_ARGS,
+        message=f"args cannot override the driver-owned flag {token.split('=', 1)[0]!r}",
     )
 
 
@@ -45,7 +56,9 @@ def reject_unsupported(req: Request, supported: Iterable[str]) -> Diagnostic | N
     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 Diagnostic(
+                code=ErrorCode.UNSUPPORTED_OPTION, message=f"driver {req.driver!r} does not support {name}"
+            )
     return None
 
 
@@ -57,10 +70,17 @@ def reject_conflicts(req: Request, flags: Mapping[str, Iterable[str]]) -> Diagno
         token = _has_flag(req.args, field_flags)
         if token is not None:
             return Diagnostic(
-                code="invalid_args",
+                code=ErrorCode.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"]
+__all__ = [
+    "PORTABLE_FIELDS",
+    "reject_conflicts",
+    "reject_transport_flags",
+    "reject_unsupported",
+    "validate_args",
+    "validate_request",
+]

coding_agent_cli/_classify.py

@@ -1,4 +1,4 @@
-"""Map facts a driver collected about one run to an ``Outcome`` and ``Diagnostic``.
+"""Map transport ``RunFacts`` and driver ``Facts`` to a classified ``Result``.
 
 Rows follow the design's outcome precedence; the first matching row wins.
 """
@@ -7,15 +7,22 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass
+from typing import Literal
 
-from .types import Diagnostic, Outcome
+from .driver import Facts
+from .types import Diagnostic, ErrorCode, Outcome, Result
 
-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")
+StopCause = Literal["exited", "cancelled", "timeout", "idle_timeout"]
 
-_KEYWORDS: dict[str, tuple[str, ...]] = {
-    "auth": (
+_CLI_KEYWORD_ORDER: tuple[ErrorCode, ...] = (
+    ErrorCode.AUTH,
+    ErrorCode.INVALID_MODEL,
+    ErrorCode.CONTEXT_OVERFLOW,
+    ErrorCode.SERVICE_ERROR,
+)
+
+_KEYWORDS: dict[ErrorCode, tuple[str, ...]] = {
+    ErrorCode.AUTH: (
         "authentication",
         "unauthorized",
         "forbidden",
@@ -25,9 +32,9 @@ _KEYWORDS: dict[str, tuple[str, ...]] = {
         "login required",
         "auth_unavailable",
     ),
-    "invalid_model": ("invalid model", "unknown model", "not a valid model"),
-    "context_overflow": ("context_length_exceeded",),
-    "service_error": (
+    ErrorCode.INVALID_MODEL: ("invalid model", "unknown model", "not a valid model"),
+    ErrorCode.CONTEXT_OVERFLOW: ("context_length_exceeded",),
+    ErrorCode.SERVICE_ERROR: (
         "overloaded",
         "rate limit",
         "rate_limit",
@@ -38,133 +45,217 @@ _KEYWORDS: dict[str, tuple[str, ...]] = {
     ),
 }
 _CONTEXT_OVERFLOW_RE = re.compile(r"\bcontext_length_exceeded\b")
+_MODEL_NOT_FOUND_RE = re.compile(r'\bmodel\s+"[^"]+"\s+not\s+found\b')
+_HTTP_STATUS_RE = re.compile(
+    r"""\b(?:http(?:/\d(?:\.\d)?)?(?:\s+error)?|status(?:\s+code)?)\s*[:=]?\s*"?([1-5]\d{2})\b"""
+    r"""|"(?:status|status_code|statusCode)"\s*:\s*(\d{3})\b""",
+    re.IGNORECASE,
+)
 
 
 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 ""."""
+def _http_codes_from_text(text: str) -> set[ErrorCode]:
+    codes = (http_status_code(int(m.group(1) or m.group(2))) for m in _HTTP_STATUS_RE.finditer(text))
+    return {code for code in codes if code is not None}
+
+
+def keyword_code(text: str) -> ErrorCode | None:
+    """Return the first CLI ``ErrorCode`` whose keywords appear in ``text``, in precedence order, or ``None``."""
     lowered = _normalize(text)
     if not lowered.strip():
-        return ""
-    for code in CLI_CODES:
-        if code == "context_overflow":
+        return None
+    http_codes = _http_codes_from_text(lowered)
+    for code in _CLI_KEYWORD_ORDER:
+        if code == ErrorCode.CONTEXT_OVERFLOW:
             if _CONTEXT_OVERFLOW_RE.search(lowered):
                 return code
-        elif any(token in lowered for token in _KEYWORDS[code]):
+        elif code == ErrorCode.INVALID_MODEL and _MODEL_NOT_FOUND_RE.search(lowered):
+            return code
+        elif any(token in lowered for token in _KEYWORDS[code]) or code in http_codes:
             return code
-    return ""
+    return None
 
 
-def http_status_code(status: int | None) -> str:
-    """Map a CLI-reported HTTP status to a CLI code, or ""."""
+def http_status_code(status: int | None) -> ErrorCode | None:
+    """Map a CLI-reported HTTP status to an ``ErrorCode``, or ``None``."""
     if status in (401, 403):
-        return "auth"
+        return ErrorCode.AUTH
     if status == 429 or (status is not None and 500 <= status <= 599):
-        return "service_error"
-    return ""
+        return ErrorCode.SERVICE_ERROR
+    return None
 
 
-@dataclass(slots=True, kw_only=True)
-class Facts:
-    """What a driver observed. ``cli_error`` is structured CLI error data; ``diagnostics`` is free text."""
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RunFacts:
+    """Transport and supervision facts collected for one run."""
 
-    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 = ""
+    stop_cause: StopCause = "exited"
     returncode: int | None = None
+    stderr_tail: str = ""
+    request_error: Diagnostic | None = None
+    spawn_error: Diagnostic | None = None
+    stdin_failed: str | None = None
+    parser_error: str | None = None
+    cleanup_incomplete: bool = False
+    line_too_long: bool = False
+    duration_s: float = 0.0
 
 
-@dataclass(frozen=True, slots=True)
-class Classification:
-    outcome: Outcome
-    error: Diagnostic | None
-    warnings: tuple[Diagnostic, ...] = ()
+def _message(*parts: str) -> str:
+    return "\n".join(part.strip() for part in parts if part and part.strip())
 
 
-_CLI_OUTCOMES = {
-    "auth": Outcome.AGENT_FATAL,
-    "invalid_model": Outcome.REQUEST_FATAL,
-    "context_overflow": Outcome.REQUEST_FATAL,
-    "service_error": Outcome.RETRYABLE,
-}
+def _cli_diagnostic(run: RunFacts, facts: Facts) -> Diagnostic | None:
+    """Return structured ``Facts.error`` if set, else keyword-match ``Facts.error_text`` and ``stderr_tail``."""
+    if facts.error is not None:
+        return facts.error
+    combined = _message(facts.error_text, run.stderr_tail)
+    code = keyword_code(combined)
+    if code is not None:
+        return Diagnostic(code=code, message=combined)
+    return None
 
 
-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 _build_warnings(run: RunFacts, extra: tuple[Diagnostic, ...] = ()) -> tuple[Diagnostic, ...]:
+    warnings: list[Diagnostic] = []
+    if run.line_too_long:
+        warnings.append(
+            Diagnostic(code=ErrorCode.LINE_TOO_LONG, message="a line exceeded max_line_bytes and was discarded")
+        )
+    if run.cleanup_incomplete:
+        warnings.append(
+            Diagnostic(
+                code=ErrorCode.CLEANUP_INCOMPLETE,
+                message="process cleanup did not complete before deadline",
+            )
+        )
+    warnings.extend(extra)
+    return tuple(warnings)
 
 
-def _message(*parts: str) -> str:
-    return "\n".join(part.strip() for part in parts if part and part.strip())
+def _result(
+    run: RunFacts,
+    facts: Facts,
+    *,
+    text: str,
+    outcome: Outcome,
+    error: Diagnostic | None,
+    extra_warnings: tuple[Diagnostic, ...] = (),
+) -> Result:
+    return Result(
+        outcome=outcome,
+        text=text,
+        session_id=facts.session_id or None,
+        model=facts.model,
+        usage=facts.usage,
+        cost_usd=facts.cost_usd,
+        duration_s=run.duration_s,
+        num_turns=facts.num_turns,
+        stop_reason=facts.stop_reason,
+        returncode=run.returncode,
+        error=error,
+        warnings=_build_warnings(run, extra_warnings),
+    )
 
 
-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)
+def classify(run: RunFacts, facts: Facts, *, text: str) -> Result:
+    """Classify one run into a ``Result`` according to the design's 12-row precedence table."""
+    result_text = facts.final_text if facts.final_text is not None else text
+
+    # Row 1: Latched stop cause is cancelled
+    if run.stop_cause == "cancelled":
+        return _result(
+            run,
+            facts,
+            text=result_text,
+            outcome=Outcome.CANCELLED,
+            error=Diagnostic(code=ErrorCode.CANCELLED, message="run cancelled"),
         )
-    # 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")
+    # Row 2: Validation failure or RequestError
+    if run.request_error is not None:
+        return _result(run, facts, text=result_text, outcome=Outcome.REQUEST_FATAL, error=run.request_error)
+    # Row 3: Executable missing or spawn denied
+    if run.spawn_error is not None:
+        return _result(run, facts, text=result_text, outcome=Outcome.AGENT_FATAL, error=run.spawn_error)
+
+    cli = _cli_diagnostic(run, facts)
+
+    # Row 4: Auth failure
+    if cli is not None and cli.code == ErrorCode.AUTH:
+        return _result(run, facts, text=result_text, outcome=Outcome.AGENT_FATAL, error=cli)
+    # Row 5: Invalid model or context overflow
+    if cli is not None and cli.code in (ErrorCode.INVALID_MODEL, ErrorCode.CONTEXT_OVERFLOW):
+        return _result(run, facts, text=result_text, outcome=Outcome.REQUEST_FATAL, error=cli)
+    # Row 6: Parser raised
+    if run.parser_error is not None:
+        return _result(
+            run,
+            facts,
+            text=result_text,
+            outcome=Outcome.AGENT_FATAL,
+            error=Diagnostic(code=ErrorCode.PARSER_ERROR, message=run.parser_error),
         )
-    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),
+    # Row 7: CLI reports a caller-set limit
+    if cli is not None and cli.code in (ErrorCode.MAX_TURNS, ErrorCode.BUDGET):
+        return _result(run, facts, text=result_text, outcome=Outcome.LIMIT_REACHED, error=cli)
+    # Row 8: Latched stop cause is a deadline
+    if run.stop_cause in ("timeout", "idle_timeout"):
+        code = ErrorCode.TIMEOUT if run.stop_cause == "timeout" else ErrorCode.IDLE_TIMEOUT
+        msg = "run timed out" if code == ErrorCode.TIMEOUT else "run idle-timed out"
+        return _result(
+            run,
+            facts,
+            text=result_text,
+            outcome=Outcome.RETRYABLE,
+            error=Diagnostic(code=code, message=msg),
+        )
+    # Row 9: HTTP 5xx, overload, or rate limit
+    if cli is not None and cli.code == ErrorCode.SERVICE_ERROR:
+        return _result(run, facts, text=result_text, outcome=Outcome.RETRYABLE, error=cli)
+    # Row 10: Stdin failure, nonzero exit, or structured failure
+    if run.stdin_failed is not None:
+        return _result(
+            run,
+            facts,
+            text=result_text,
+            outcome=Outcome.RETRYABLE,
+            error=Diagnostic(
+                code=ErrorCode.STDIN_FAILED, message=run.stdin_failed or "failed to write prompt to stdin"
+            ),
+        )
+    if facts.error is not None:
+        return _result(run, facts, text=result_text, outcome=Outcome.RETRYABLE, error=facts.error)
+    if run.returncode:
+        return _result(
+            run,
+            facts,
+            text=result_text,
+            outcome=Outcome.RETRYABLE,
+            error=Diagnostic(
+                code=ErrorCode.EXECUTION_ERROR,
+                message=_message(f"command exited with status {run.returncode}", facts.error_text, run.stderr_tail),
             ),
         )
-    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: No text
+    if not result_text.strip():
+        return _result(
+            run,
+            facts,
+            text=result_text,
+            outcome=Outcome.RETRYABLE,
+            error=Diagnostic(
+                code=ErrorCode.NO_OUTPUT,
+                message=_message("the CLI produced no assistant text", facts.error_text, run.stderr_tail),
+            ),
         )
-    # Row 11
+    # Row 12: Otherwise
+    extra: tuple[Diagnostic, ...] = ()
     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)
+        extra = (Diagnostic(code=ErrorCode.NO_SESSION_ID, message="the CLI reported no session ID"),)
+    return _result(run, facts, text=result_text, outcome=Outcome.SUCCESS, error=None, extra_warnings=extra)
 
 
-__all__ = ["Classification", "Facts", "classify", "http_status_code", "keyword_code"]
+__all__ = ["RunFacts", "StopCause", "classify", "http_status_code", "keyword_code"]