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

coding_cli_runtime/__init__.py

@@ -0,0 +1,108 @@
+"""Runtime primitives for orchestrating LLM provider CLIs."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .auth import AuthResolution, resolve_auth
+from .codex_cli import CodexExecSpec, build_codex_exec_spec
+from .contracts import (
+    AuthMode,
+    ClaudeReasoningPolicy,
+    CliLaunchSpec,
+    CliRunRequest,
+    CliRunResult,
+    ErrorCode,
+)
+from .failure_classification import FailureClassification, classify_provider_failure
+from .provider_controls import build_model_id, resolve_provider_model_controls
+from .provider_specs import (
+    ChoiceSpec,
+    ControlSpec,
+    ModelSpec,
+    ProviderSpec,
+    get_claude_default_model,
+    get_claude_effort_levels,
+    get_claude_model_candidates,
+    get_claude_output_suffixes,
+    get_claude_permission_modes,
+    get_codex_supported_models,
+    get_copilot_default_model,
+    get_copilot_model_catalog,
+    get_gemini_default_model,
+    get_gemini_model_options,
+    get_provider_spec,
+    list_provider_specs,
+    serialize_provider_specs,
+)
+from .reasoning import resolve_claude_reasoning_policy
+from .redaction import redact_text
+from .schema_validation import SchemaValidationError, load_schema, validate_payload
+from .session_execution import (
+    InteractiveCliRunResult,
+    SessionExecutionTimeoutError,
+    SessionProgressEvent,
+    SessionRetryDecision,
+    TranscriptMirrorStrategy,
+    mirror_session_transcript,
+    run_interactive_session,
+)
+from .session_logs import (
+    claude_project_key,
+    find_claude_session,
+    find_codex_session,
+    normalize_path_str,
+)
+from .subprocess_runner import run_cli_command, run_cli_command_sync
+
+__all__ = [
+    "AuthMode",
+    "AuthResolution",
+    "CliRunRequest",
+    "CliRunResult",
+    "CodexExecSpec",
+    "ChoiceSpec",
+    "ClaudeReasoningPolicy",
+    "CliLaunchSpec",
+    "ControlSpec",
+    "ErrorCode",
+    "FailureClassification",
+    "ModelSpec",
+    "ProviderSpec",
+    "SchemaValidationError",
+    "InteractiveCliRunResult",
+    "SessionProgressEvent",
+    "SessionRetryDecision",
+    "SessionExecutionTimeoutError",
+    "TranscriptMirrorStrategy",
+    "get_claude_default_model",
+    "get_claude_effort_levels",
+    "get_claude_model_candidates",
+    "get_claude_output_suffixes",
+    "get_claude_permission_modes",
+    "get_codex_supported_models",
+    "get_copilot_default_model",
+    "get_copilot_model_catalog",
+    "get_gemini_default_model",
+    "get_gemini_model_options",
+    "get_provider_spec",
+    "list_provider_specs",
+    "build_model_id",
+    "build_codex_exec_spec",
+    "classify_provider_failure",
+    "load_schema",
+    "resolve_auth",
+    "resolve_claude_reasoning_policy",
+    "resolve_provider_model_controls",
+    "redact_text",
+    "claude_project_key",
+    "find_claude_session",
+    "find_codex_session",
+    "normalize_path_str",
+    "mirror_session_transcript",
+    "run_cli_command",
+    "run_cli_command_sync",
+    "run_interactive_session",
+    "serialize_provider_specs",
+    "validate_payload",
+]

coding_cli_runtime/auth.py

@@ -0,0 +1,55 @@
+"""Provider auth resolution contract for shared runtime."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from .contracts import AuthMode
+
+
+@dataclass(frozen=True)
+class AuthResolution:
+    provider: str
+    mode: AuthMode
+    required_env: tuple[str, ...]
+    present_env: tuple[str, ...]
+    missing_env: tuple[str, ...]
+    hint: str
+
+
+_PROVIDER_ENV_HINTS: dict[str, tuple[tuple[str, ...], str]] = {
+    "claude": (("CLAUDE_API_KEY",), "Use `claude login` or set CLAUDE_API_KEY."),
+    "copilot": (
+        tuple(),
+        "Use `copilot auth login` (CLI login is the default authentication mode).",
+    ),
+    "codex": (("OPENAI_API_KEY",), "Use Codex login flow or set OPENAI_API_KEY."),
+    "gemini": (("GEMINI_API_KEY",), "Use `gemini auth login` or set GEMINI_API_KEY."),
+}
+
+
+def resolve_auth(provider: str, env: dict[str, str] | None = None) -> AuthResolution:
+    provider_key = provider.strip().lower()
+    required_env, hint = _PROVIDER_ENV_HINTS.get(
+        provider_key,
+        (tuple(), "Unknown provider; configure CLI login or provider token env vars."),
+    )
+    current_env = env if env is not None else os.environ
+
+    present_env = tuple(key for key in required_env if current_env.get(key))
+    missing_env = tuple(key for key in required_env if key not in present_env)
+
+    if required_env and present_env:
+        mode = AuthMode.ENV
+    else:
+        mode = AuthMode.CLI_LOGIN
+
+    return AuthResolution(
+        provider=provider_key,
+        mode=mode,
+        required_env=required_env,
+        present_env=present_env,
+        missing_env=missing_env,
+        hint=hint,
+    )

coding_cli_runtime/codex_cli.py

@@ -0,0 +1,95 @@
+"""Reusable Codex CLI launch helpers."""
+
+from __future__ import annotations
+
+import json
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .provider_controls import resolve_provider_model_controls
+
+
+@dataclass(frozen=True)
+class CodexExecSpec:
+    cmd_parts: tuple[str, ...]
+    display_text: str
+    applied_controls: dict[str, Any]
+    effective_reasoning: str
+
+
+def _resolve_codex_reasoning(
+    *,
+    model_reasoning: str | None = None,
+    model_controls: dict[str, Any] | None = None,
+) -> tuple[dict[str, Any], str]:
+    controls = resolve_provider_model_controls(
+        provider="codex",
+        model_reasoning=model_reasoning,
+        model_controls=model_controls,
+    )
+    applied_raw = controls.get("applied")
+    applied_controls = applied_raw if isinstance(applied_raw, dict) else {}
+    effective_reasoning_raw = applied_controls.get("reasoning_effort")
+    if isinstance(effective_reasoning_raw, str) and effective_reasoning_raw.strip():
+        return applied_controls, effective_reasoning_raw
+    if isinstance(model_reasoning, str) and model_reasoning.strip():
+        return applied_controls, model_reasoning
+    raise ValueError("Codex launch requires a reasoning effort")
+
+
+def build_codex_exec_spec(
+    *,
+    codex_bin: str,
+    model: str,
+    cwd: Path,
+    output_schema_path: Path,
+    output_path: Path,
+    model_reasoning: str | None = None,
+    model_controls: dict[str, Any] | None = None,
+    json_output: bool,
+    sandbox: str,
+    full_auto: bool = True,
+    skip_git_repo_check: bool = True,
+    extra_args: tuple[str, ...] | list[str] | None = None,
+    stdin_placeholder: str | None = "<prompt>",
+) -> CodexExecSpec:
+    applied_controls, effective_reasoning = _resolve_codex_reasoning(
+        model_reasoning=model_reasoning,
+        model_controls=model_controls,
+    )
+    reasoning_config_value = json.dumps(effective_reasoning)
+    cmd_parts: list[str] = [str(codex_bin), "exec"]
+    if json_output:
+        cmd_parts.append("--json")
+    if full_auto:
+        cmd_parts.append("--full-auto")
+    cmd_parts.extend(["--sandbox", sandbox])
+    if skip_git_repo_check:
+        cmd_parts.append("--skip-git-repo-check")
+    cmd_parts.extend(
+        [
+            "--model",
+            model,
+            "--config",
+            f"model_reasoning_effort={reasoning_config_value}",
+            "-C",
+            str(cwd),
+            "--output-schema",
+            str(output_schema_path),
+            "-o",
+            str(output_path),
+        ]
+    )
+    if extra_args:
+        cmd_parts.extend([str(part) for part in extra_args])
+    display_parts = [shlex.quote(part) for part in cmd_parts]
+    if stdin_placeholder is not None:
+        display_parts.append(stdin_placeholder)
+    return CodexExecSpec(
+        cmd_parts=tuple(cmd_parts),
+        display_text=" ".join(display_parts),
+        applied_controls=applied_controls,
+        effective_reasoning=effective_reasoning,
+    )

coding_cli_runtime/contracts.py

@@ -0,0 +1,72 @@
+"""Core contracts for shared CLI runtime execution."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+
+class ErrorCode(str, Enum):
+    NONE = "none"
+    SPAWN_FAILED = "spawn_failed"
+    TIMED_OUT = "timed_out"
+    NON_ZERO_EXIT = "non_zero_exit"
+
+
+class AuthMode(str, Enum):
+    NONE = "none"
+    ENV = "env"
+    CLI_LOGIN = "cli_login"
+    TOKEN_FILE = "token_file"
+
+
+@dataclass(frozen=True)
+class CliRunRequest:
+    cmd_parts: tuple[str, ...]
+    cwd: Path
+    stdin_text: str | None = None
+    env: dict[str, str] | None = None
+    timeout_seconds: float | None = None
+    stdout_stream_path: Path | None = None
+    stderr_stream_path: Path | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "cmd_parts", tuple(self.cmd_parts))
+        if self.env is not None:
+            object.__setattr__(self, "env", dict(self.env))
+
+
+@dataclass(frozen=True)
+class CliLaunchSpec:
+    cmd_parts: tuple[str, ...]
+    display_text: str
+    stdin_text: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "cmd_parts", tuple(self.cmd_parts))
+
+
+@dataclass(frozen=True)
+class CliRunResult:
+    command: Sequence[str]
+    returncode: int | None
+    stdout_text: str
+    stderr_text: str
+    duration_seconds: float
+    timed_out: bool
+    error_code: ErrorCode
+    error_message: str | None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "command", tuple(self.command))
+
+
+@dataclass(frozen=True)
+class ClaudeReasoningPolicy:
+    mode: str
+    effective_effort: str | None
+    effort_source: str | None
+    thinking_tokens: int | None
+    disable_via_env_setting: bool = False

coding_cli_runtime/copilot_reasoning_baseline.json

@@ -0,0 +1,66 @@
+{
+  "copilot_cli_version": "1.0.15-0",
+  "source_probe_run": "packages/coding-cli-runtime/playground/copilot-cli/experiments/results/reasoning_probe_20260331_165652",
+  "models": {
+    "claude-sonnet-4.6": {
+      "schema": "reasoning_effort",
+      "value": "medium",
+      "default_reasoning": "medium"
+    },
+    "claude-sonnet-4.5": {
+      "schema": "thinking_budget",
+      "value": "1024"
+    },
+    "claude-haiku-4.5": {
+      "schema": "thinking_budget",
+      "value": "1024"
+    },
+    "claude-opus-4.6": {
+      "schema": "reasoning_effort",
+      "value": "high",
+      "default_reasoning": "high"
+    },
+    "claude-opus-4.5": {
+      "schema": "thinking_budget",
+      "value": "1024"
+    },
+    "claude-sonnet-4": {
+      "schema": "thinking_budget",
+      "value": "1024"
+    },
+    "goldeneye": {
+      "schema": "reasoning_effort",
+      "value": "medium",
+      "default_reasoning": "medium",
+      "supported_reasoning_efforts": ["low", "medium", "high"]
+    },
+    "gpt-5.4": {
+      "schema": "reasoning_effort",
+      "value": "medium",
+      "default_reasoning": "medium"
+    },
+    "gpt-5.3-codex": {
+      "schema": "reasoning_effort",
+      "value": "medium",
+      "default_reasoning": "medium"
+    },
+    "gpt-5.2": {
+      "schema": "reasoning_effort",
+      "value": "medium",
+      "default_reasoning": "medium"
+    },
+    "gpt-5.1": {
+      "schema": "reasoning_effort",
+      "value": "medium",
+      "default_reasoning": "medium"
+    },
+    "gpt-5-mini": {
+      "schema": "reasoning_effort",
+      "value": "medium",
+      "default_reasoning": "medium"
+    },
+    "gpt-4.1": {
+      "schema": "none"
+    }
+  }
+}

coding_cli_runtime/copilot_reasoning_logs.py

@@ -0,0 +1,81 @@
+"""Copilot share-export and process-log parsing helpers."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+SESSION_ID_RE = re.compile(r"\*\*Session ID:\*\*\s*`([^`]+)`")
+DEFAULT_REASONING_RE = re.compile(r"defaultReasoningEffort=([A-Za-z0-9_-]+)")
+
+
+def extract_session_id(markdown_text: str) -> str | None:
+    match = SESSION_ID_RE.search(markdown_text)
+    return match.group(1) if match else None
+
+
+def extract_final_request_options(log_text: str) -> dict[str, Any]:
+    marker = "Final request options:"
+    idx = log_text.find(marker)
+    if idx < 0:
+        return {}
+
+    start = log_text.find("{", idx)
+    if start < 0:
+        return {}
+
+    try:
+        parsed, _ = json.JSONDecoder().raw_decode(log_text[start:])
+    except json.JSONDecodeError:
+        return {}
+    if not isinstance(parsed, Mapping):
+        return {}
+    return dict(parsed)
+
+
+def classify_reasoning_fields(options: Mapping[str, Any]) -> tuple[str, str, str, str]:
+    reasoning_effort = options.get("reasoning_effort")
+    thinking_budget = options.get("thinking_budget")
+    if reasoning_effort is not None:
+        value = str(reasoning_effort)
+        return "reasoning_effort", value, value, ""
+    if thinking_budget is not None:
+        value = str(thinking_budget)
+        return "thinking_budget", value, "", value
+    return "none", "", "", ""
+
+
+def extract_default_reasoning(log_text: str) -> str:
+    match = DEFAULT_REASONING_RE.search(log_text)
+    return match.group(1) if match else ""
+
+
+def find_process_log_for_session(
+    session_id: str,
+    logs_dir: Path,
+    *,
+    max_candidates: int = 400,
+) -> Path | None:
+    if not session_id or not logs_dir.exists():
+        return None
+
+    candidates: list[tuple[float, Path]] = []
+    for path in logs_dir.glob("process-*.log"):
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            continue
+        candidates.append((mtime, path))
+
+    candidates.sort(key=lambda item: item[0], reverse=True)
+    for _, path in candidates[:max_candidates]:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        if session_id in text:
+            return path
+    return None

coding_cli_runtime/failure_classification.py

@@ -0,0 +1,183 @@
+"""Provider stderr classification for retry and failure-injection handling."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FailureClassification:
+    provider: str
+    retryable: bool
+    category: str
+
+
+def _classify_gemini(stderr_text: str) -> FailureClassification:
+    lowered = stderr_text.lower()
+
+    auth_expiry_markers = (
+        "authentication timed out",
+        "token expired",
+        "refresh token",
+        "please run gemini auth login",
+        "reauthenticate",
+    )
+    if any(marker in lowered for marker in auth_expiry_markers):
+        return FailureClassification(provider="gemini", retryable=False, category="auth_expired")
+
+    auth_or_permission_markers = (
+        "invalid api key",
+        "permission denied",
+        "unauthorized",
+        "forbidden",
+    )
+    if any(marker in lowered for marker in auth_or_permission_markers):
+        return FailureClassification(
+            provider="gemini", retryable=False, category="auth_or_permission"
+        )
+
+    rate_limit_markers = (
+        "quota",
+        "rate limit",
+        "resource exhausted",
+        "insufficient_quota",
+        "exhausted your capacity",
+        "billing",
+    )
+    if any(marker in lowered for marker in rate_limit_markers):
+        return FailureClassification(provider="gemini", retryable=False, category="rate_limited")
+
+    always_transient_markers = (
+        "eai_again",
+        "getaddrinfo",
+        "temporary failure in name resolution",
+        "enotfound",
+        "etimedout",
+        "econnreset",
+        "econnrefused",
+        "socket hang up",
+    )
+    if any(marker in lowered for marker in always_transient_markers):
+        return FailureClassification(
+            provider="gemini", retryable=True, category="network_transient"
+        )
+
+    stdin_transport_markers = ("no input provided via stdin",)
+    if any(marker in lowered for marker in stdin_transport_markers):
+        return FailureClassification(
+            provider="gemini", retryable=True, category="cli_stdin_transient"
+        )
+
+    weak_transient_markers = (
+        "network error",
+        "failed, reason:",
+    )
+    if not any(marker in lowered for marker in weak_transient_markers):
+        return FailureClassification(provider="gemini", retryable=False, category="unknown")
+
+    signal_markers = (
+        "cloudcode-pa.googleapis.com",
+        "streamgeneratecontent",
+        "loadcodeassist",
+        "gaxioserror",
+        "fetcherror",
+    )
+    if any(marker in lowered for marker in signal_markers):
+        return FailureClassification(
+            provider="gemini", retryable=True, category="network_transient"
+        )
+
+    return FailureClassification(provider="gemini", retryable=False, category="unknown")
+
+
+def _classify_copilot(stderr_text: str) -> FailureClassification:
+    lowered = stderr_text.lower()
+
+    auth_markers = (
+        "no authentication information found",
+        "copilot can be authenticated",
+        "gh auth login",
+    )
+    if any(marker in lowered for marker in auth_markers):
+        return FailureClassification(provider="copilot", retryable=False, category="auth_missing")
+
+    # Copilot CLI sometimes exits before producing stderr and only logs this in
+    # ~/.copilot/logs/process-*.log. Treat this startup path as transient.
+    startup_rate_limit_markers = (
+        "failed to list models: 429",
+        "error posting to endpoint: too many requests",
+        "failed to open sse stream",
+        "error loading models",
+    )
+    if any(marker in lowered for marker in startup_rate_limit_markers):
+        return FailureClassification(
+            provider="copilot", retryable=True, category="startup_rate_limited"
+        )
+
+    session_store_lock_markers = (
+        "database is locked",
+        "session store",
+    )
+    if all(marker in lowered for marker in session_store_lock_markers):
+        return FailureClassification(
+            provider="copilot", retryable=True, category="session_store_locked"
+        )
+
+    return FailureClassification(provider="copilot", retryable=False, category="unknown")
+
+
+def _classify_claude(stderr_text: str) -> FailureClassification:
+    lowered = stderr_text.lower()
+
+    auth_markers = (
+        "not authenticated",
+        "authentication required",
+        "please run claude auth login",
+        "please run /login",
+        "invalid api key",
+        "unauthorized",
+        "forbidden",
+    )
+    if any(marker in lowered for marker in auth_markers):
+        return FailureClassification(provider="claude", retryable=False, category="auth_missing")
+
+    rate_limit_markers = (
+        "rate limit",
+        "too many requests",
+        "quota",
+        "insufficient_quota",
+    )
+    if any(marker in lowered for marker in rate_limit_markers):
+        return FailureClassification(provider="claude", retryable=False, category="rate_limited")
+
+    transient_markers = (
+        "overloaded",
+        "temporarily unavailable",
+        "please try again",
+        "eai_again",
+        "getaddrinfo",
+        "temporary failure in name resolution",
+        "enotfound",
+        "etimedout",
+        "econnreset",
+        "econnrefused",
+        "socket hang up",
+        "network error",
+    )
+    if any(marker in lowered for marker in transient_markers):
+        return FailureClassification(
+            provider="claude", retryable=True, category="network_transient"
+        )
+
+    return FailureClassification(provider="claude", retryable=False, category="unknown")
+
+
+def classify_provider_failure(*, provider: str, stderr_text: str) -> FailureClassification:
+    provider_key = provider.strip().lower()
+    if provider_key == "gemini":
+        return _classify_gemini(stderr_text)
+    if provider_key == "copilot":
+        return _classify_copilot(stderr_text)
+    if provider_key == "claude":
+        return _classify_claude(stderr_text)
+    return FailureClassification(provider=provider_key, retryable=False, category="unknown")