coding-cli-runtime 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

coding_cli_runtime/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from .auth import AuthResolution, resolve_auth
 from .codex_cli import CodexExecSpec, build_codex_exec_spec
@@ -15,6 +15,12 @@ from .contracts import (
     ErrorCode,
 )
 from .failure_classification import FailureClassification, classify_provider_failure
+from .headless import (
+    build_claude_headless_core,
+    build_codex_headless_core,
+    build_copilot_headless_core,
+    build_gemini_headless_core,
+)
 from .provider_contracts import (
     ApprovalContract,
     AuthContract,
@@ -97,7 +103,12 @@ __all__ = [
     "SessionRetryDecision",
     "SessionExecutionTimeoutError",
     "TranscriptMirrorStrategy",
+    "build_claude_headless_core",
+    "build_codex_exec_spec",
+    "build_codex_headless_core",
+    "build_copilot_headless_core",
     "build_env_overlay",
+    "build_gemini_headless_core",
     "get_claude_default_model",
     "get_claude_effort_levels",
     "get_claude_model_candidates",
@@ -112,7 +123,6 @@ __all__ = [
     "get_provider_spec",
     "list_provider_specs",
     "build_model_id",
-    "build_codex_exec_spec",
     "classify_provider_failure",
     "load_schema",
     "render_prompt",

coding_cli_runtime/codex_cli.py

@@ -60,18 +60,20 @@ def build_codex_exec_spec(
         model_controls=model_controls,
     )
     reasoning_config_value = json.dumps(effective_reasoning)
-    cmd_parts: list[str] = [str(codex_bin), "exec"]
+
+    from .headless import build_codex_headless_core
+
+    cmd_parts: list[str] = build_codex_headless_core(
+        model,
+        binary=str(codex_bin),
+        sandbox_mode=sandbox if sandbox else None,
+        full_auto=full_auto,
+        skip_git_repo_check=skip_git_repo_check,
+    )
     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",

coding_cli_runtime/headless.py

@@ -0,0 +1,124 @@
+"""Per-provider headless launch core helpers.
+
+Each helper emits the standard headless launch args for its provider,
+derived from ``ProviderContract.headless``. Consumers append their own
+app-specific tails (tool restrictions, output paths, prompt, etc.).
+
+These helpers are the canonical source for headless launch flag assembly
+within ``coding_cli_runtime``. In-repo consumers (feather, codex_cli,
+provider_contracts builder) delegate to them. App-generation provider
+wrappers may still assemble flags directly when their command construction
+is interleaved with consumer-specific logic (reasoning config, output
+format, artifact paths).
+"""
+
+from __future__ import annotations
+
+from .provider_contracts import get_provider_contract
+
+
+def build_claude_headless_core(
+    model: str,
+    *,
+    binary: str | None = None,
+    permission_mode: str | None = None,
+    skip_permissions: bool = True,
+) -> list[str]:
+    """Build Claude headless launch core args.
+
+    Returns args up to and including ``--model``. Does NOT include prompt,
+    output format, tool restrictions, or other app-specific flags.
+    """
+    contract = get_provider_contract("claude")
+    h = contract.headless
+    cmd: list[str] = [binary or contract.binary]
+    cmd.extend(h.activation_args)
+    if h.approval.permission_mode_flag:
+        mode = permission_mode or h.approval.default_permission_mode
+        if mode:
+            cmd.extend([h.approval.permission_mode_flag, mode])
+    if skip_permissions and h.approval.flag:
+        cmd.append(h.approval.flag)
+    cmd.extend(["--model", model])
+    return cmd
+
+
+def build_codex_headless_core(
+    model: str,
+    *,
+    binary: str | None = None,
+    sandbox_mode: str | None = None,
+    full_auto: bool = True,
+    skip_git_repo_check: bool = True,
+) -> list[str]:
+    """Build Codex headless launch core args.
+
+    Returns args including ``exec``, ``--full-auto``, ``--sandbox``,
+    ``--skip-git-repo-check``, and ``--model``. Does NOT include
+    ``-C``, ``-o``, ``--output-schema``, or reasoning config.
+
+    Args:
+        full_auto: Include ``--full-auto`` (default True).
+        skip_git_repo_check: Include ``--skip-git-repo-check`` (default True).
+    """
+    contract = get_provider_contract("codex")
+    h = contract.headless
+    cmd: list[str] = [binary or contract.binary]
+    cmd.extend(h.activation_args)
+    if full_auto and h.noninteractive_mode_flag:
+        cmd.append(h.noninteractive_mode_flag)
+    if h.sandbox is not None:
+        mode = sandbox_mode or h.sandbox.writable_mode
+        cmd.extend([h.sandbox.flag, mode])
+    if skip_git_repo_check and h.requires_git_repo and h.skip_git_repo_flag:
+        cmd.append(h.skip_git_repo_flag)
+    cmd.extend(["--model", model])
+    return cmd
+
+
+def build_copilot_headless_core(
+    model: str,
+    *,
+    binary: str | None = None,
+    stream: str | None = None,
+) -> list[str]:
+    """Build Copilot headless launch core args.
+
+    Returns args including activation (``--no-ask-user``,
+    ``--no-custom-instructions``), ``--allow-all``, ``--stream``,
+    and ``--model``. Does NOT include ``-p``, ``--share``, or
+    force-implementation.
+    """
+    contract = get_provider_contract("copilot")
+    h = contract.headless
+    cmd: list[str] = [binary or contract.binary]
+    cmd.extend(h.activation_args)
+    if h.approval.flag:
+        cmd.append(h.approval.flag)
+    cmd.extend(["--model", model])
+    if h.stream_flag:
+        stream_value = stream or h.default_stream_mode
+        if stream_value:
+            cmd.extend([h.stream_flag, stream_value])
+    return cmd
+
+
+def build_gemini_headless_core(
+    model: str,
+    *,
+    binary: str | None = None,
+) -> list[str]:
+    """Build Gemini headless launch core args.
+
+    Returns args including approval flag (``--yolo``) and ``--model``.
+    Does NOT include ``--prompt ""`` activation (that's part of prompt
+    transport, handled by ``render_prompt()``).
+    """
+    contract = get_provider_contract("gemini")
+    h = contract.headless
+    cmd: list[str] = [binary or contract.binary]
+    cmd.extend(h.activation_args)
+    if h.approval.flag:
+        cmd.append(h.approval.flag)
+    cmd.extend(["--model", model])
+    return cmd

coding_cli_runtime/provider_contracts.py

@@ -406,47 +406,53 @@ def _build_non_interactive_run(
     stream: str | None = None,
     extra_flags: tuple[str, ...] = (),
 ) -> NonInteractiveRunSpec:
-    """Build a non-interactive CLI run spec. Internal convenience."""
-    contract = get_provider_contract(provider_id)
-    h = contract.headless
-
-    bin_name = binary or contract.binary
-    cmd: list[str] = [bin_name]
-
-    # Headless activation (e.g. "--print" for Claude, "exec" for Codex)
-    cmd.extend(h.activation_args)
-
-    # Non-interactive mode flag (e.g. "--full-auto" for Codex)
-    if h.noninteractive_mode_flag:
-        cmd.append(h.noninteractive_mode_flag)
-
-    # Sandbox (Codex)
-    if h.sandbox is not None:
-        mode = codex_sandbox_mode or h.sandbox.writable_mode
-        cmd.extend([h.sandbox.flag, mode])
-
-    # Git repo bypass
-    if h.requires_git_repo and h.skip_git_repo_flag:
-        cmd.append(h.skip_git_repo_flag)
+    """Build a non-interactive CLI run spec. Internal convenience.
 
-    # Approval
-    if h.approval.flag:
-        cmd.append(h.approval.flag)
-
-    # Permission mode (Claude)
-    if h.approval.permission_mode_flag:
-        mode_value = permission_mode or h.approval.default_permission_mode
-        if mode_value:
-            cmd.extend([h.approval.permission_mode_flag, mode_value])
+    Delegates headless core arg assembly to ``headless.build_*_headless_core()``
+    helpers, which derive flags from ``ProviderContract.headless``.
+    """
+    from .headless import (
+        build_claude_headless_core,
+        build_codex_headless_core,
+        build_copilot_headless_core,
+        build_gemini_headless_core,
+    )
 
-    # Model
-    cmd.extend(["--model", model])
+    contract = get_provider_contract(provider_id)
+    h = contract.headless
+    key = provider_id.strip().lower()
 
-    # Stream (Copilot)
-    if h.stream_flag:
-        stream_value = stream or h.default_stream_mode
-        if stream_value:
-            cmd.extend([h.stream_flag, stream_value])
+    # Headless core (binary + activation + approval + model + stream)
+    if key == "claude":
+        cmd = build_claude_headless_core(model, binary=binary, permission_mode=permission_mode)
+    elif key == "codex":
+        cmd = build_codex_headless_core(model, binary=binary, sandbox_mode=codex_sandbox_mode)
+    elif key == "copilot":
+        cmd = build_copilot_headless_core(model, binary=binary, stream=stream)
+    elif key == "gemini":
+        cmd = build_gemini_headless_core(model, binary=binary)
+    else:
+        # Fallback for unknown providers — generic assembly
+        bin_name = binary or contract.binary
+        cmd = [bin_name, *h.activation_args]
+        if h.noninteractive_mode_flag:
+            cmd.append(h.noninteractive_mode_flag)
+        if h.sandbox is not None:
+            mode = codex_sandbox_mode or h.sandbox.writable_mode
+            cmd.extend([h.sandbox.flag, mode])
+        if h.requires_git_repo and h.skip_git_repo_flag:
+            cmd.append(h.skip_git_repo_flag)
+        if h.approval.flag:
+            cmd.append(h.approval.flag)
+        if h.approval.permission_mode_flag:
+            mode_value = permission_mode or h.approval.default_permission_mode
+            if mode_value:
+                cmd.extend([h.approval.permission_mode_flag, mode_value])
+        cmd.extend(["--model", model])
+        if h.stream_flag:
+            stream_value = stream or h.default_stream_mode
+            if stream_value:
+                cmd.extend([h.stream_flag, stream_value])
 
     # Prompt
     payload = render_prompt(h.prompt, prompt)

coding_cli_runtime/session_logs.py

@@ -5,7 +5,11 @@ from __future__ import annotations
 import json
 import os
 import re
+from collections.abc import Callable
 from pathlib import Path
+from typing import TypeVar
+
+_T = TypeVar("_T")
 
 
 def normalize_path_str(path_str: str) -> str:
@@ -15,6 +19,58 @@ def normalize_path_str(path_str: str) -> str:
         return os.path.normpath(path_str)
 
 
+# ---------------------------------------------------------------------------
+# Generic session-directory scanning primitive
+# ---------------------------------------------------------------------------
+
+
+def scan_session_dir(
+    directory: Path,
+    *,
+    glob_pattern: str = "*.jsonl",
+    since_ts: float,
+    mtime_buffer: float = 15.0,
+    extract_fn: Callable[[Path], _T | None],
+    max_candidates: int = 200,
+) -> list[tuple[float, Path, _T]]:
+    """Scan a directory for session files, filter by mtime, extract metadata.
+
+    Returns a list of ``(mtime, path, extracted)`` tuples sorted by mtime
+    descending. Provider-specific ranking/selection stays with the caller.
+
+    Args:
+        directory: Directory to scan.
+        glob_pattern: Glob pattern for session files (default: ``*.jsonl``).
+        since_ts: Only include files with mtime >= ``since_ts - mtime_buffer``.
+        mtime_buffer: Seconds of slack before ``since_ts`` (default: 15).
+        extract_fn: Called on each candidate path. Return ``None`` to skip.
+        max_candidates: Max number of candidates to process after mtime filter.
+    """
+    if not directory.exists():
+        return []
+
+    candidates: list[tuple[float, Path]] = []
+    try:
+        for path in directory.rglob(glob_pattern):
+            try:
+                mtime = path.stat().st_mtime
+            except OSError:
+                continue
+            if mtime >= since_ts - mtime_buffer:
+                candidates.append((mtime, path))
+    except (OSError, RuntimeError):
+        return []
+
+    candidates.sort(key=lambda item: item[0], reverse=True)
+
+    results: list[tuple[float, Path, _T]] = []
+    for mtime, path in candidates[:max_candidates]:
+        extracted = extract_fn(path)
+        if extracted is not None:
+            results.append((mtime, path, extracted))
+    return results
+
+
 def codex_session_roots() -> list[Path]:
     base = Path.home() / ".codex"
     return [base / "sessions", base / "archived_sessions"]

{coding_cli_runtime-0.2.0.dist-info → coding_cli_runtime-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-cli-runtime
-Version: 0.2.0
+Version: 0.3.0
 Summary: Reusable CLI runtime primitives for provider-backed automation workflows
 Author-email: LLM Eval maintainers <llm-eval-maintainers@users.noreply.github.com>
 License-Expression: MIT
@@ -40,17 +40,21 @@ code doesn't need provider-specific subprocess handling.
 
 **What it does (and why not just `subprocess.run`):**
 
-- Unified request/result types across all four CLIs
-- Timeout enforcement with graceful process termination
-- Provider-aware failure classification (retryable vs fatal)
-- Built-in model catalog with defaults, reasoning levels, and capabilities
-- Interactive session management for long-running generation tasks
-- Zero runtime dependencies
+- Run any provider CLI with unified request/result types and timeout enforcement
+- Query the model catalog (with user-override and live-cache fallback)
+- Classify failures as retryable vs fatal per provider
+- Look up provider auth, config dirs, and headless launch flags
+- Build non-interactive launch commands without hardcoding provider flags
+- Find session logs after a run (Codex, Claude)
+- Run long-lived sessions with process-group cleanup and transcript mirroring
+- No Python package dependencies — only requires the provider CLIs themselves
 
 ## Installation
 
 ```bash
 pip install coding-cli-runtime
+# or
+uv add coding-cli-runtime
 ```
 
 Requires Python 3.10+.
@@ -65,7 +69,7 @@ from pathlib import Path
 from coding_cli_runtime import CliRunRequest, run_cli_command
 
 request = CliRunRequest(
-    cmd_parts=("codex", "--model", "o4-mini", "--quiet", "exec", "fix the tests"),
+    cmd_parts=("codex", "--model", "gpt-5.4", "--quiet", "exec", "fix the tests"),
     cwd=Path("/tmp/my-project"),
     timeout_seconds=120,
 )
@@ -180,6 +184,38 @@ can drill into whichever aspect they need. This is reference metadata,
 not a command-construction control plane — consumers keep their own
 command assembly and adopt contract fields selectively.
 
+### Build headless launch commands
+
+```python
+from coding_cli_runtime import build_claude_headless_core, build_codex_headless_core
+
+# Claude: binary + --print + --permission-mode + --dangerously-skip-permissions + --model
+cmd = build_claude_headless_core("claude-sonnet-4-6")
+cmd.extend(["--output-format", "text", "--disallowedTools", "Bash,Task"])
+
+# Codex: binary + exec + --full-auto + --sandbox + --skip-git-repo-check + --model
+cmd = build_codex_headless_core("gpt-5.4", sandbox_mode="read-only")
+cmd.extend(["-C", str(workdir)])
+```
+
+Headless core helpers emit the standard flags for non-interactive runs.
+Consumers append app-specific tails (tool restrictions, output paths, etc.).
+
+### Find session logs after a run
+
+```python
+import time
+from coding_cli_runtime import find_codex_session, find_claude_session
+
+# Find the most recent Codex session log for a given working directory
+session = find_codex_session("/path/to/project", since_ts=time.time() - 300)
+if session:
+    print(f"Session log: {session}")  # ~/.codex/sessions/.../conversation.jsonl
+```
+
+Works for Codex and Claude. Scans provider config directories for session
+files matching the working directory and time window.
+
 ## Key types
 
 | Type | Purpose |
@@ -191,11 +227,50 @@ command assembly and adopt contract fields selectively.
 | `ProviderContract` | Structured provider CLI metadata (auth, paths, headless launch) |
 | `FailureClassification` | Classified error with retryable flag and category |
 
-`run_interactive_session()` manages long-running CLI processes with
-timeout enforcement, process-group cleanup, transcript mirroring, and
-automatic retries. Only `cmd_parts`, `cwd`, `stdin_text`, and `logger` are
-required — observability labels like `job_name` and `phase_tag` default to
-sensible values so external callers don't need to invent them.
+### Run long-lived CLI sessions
+
+For CLI runs that take minutes (e.g., full app generation), use
+`run_interactive_session()` instead of `run_cli_command()`. It adds:
+
+- Process-group cleanup (kills orphaned child processes on timeout)
+- Transcript mirroring (streams CLI output to a file while the process runs)
+- Automatic retries on transient failures
+
+```python
+from coding_cli_runtime import run_interactive_session
+
+result = await run_interactive_session(
+    cmd_parts=("claude", "--print", "--model", "claude-sonnet-4-6"),
+    cwd=workdir,
+    stdin_text=prompt,
+    logger=logger,
+    timeout_seconds=600,
+)
+```
+
+Only `cmd_parts`, `cwd`, `stdin_text`, and `logger` are required.
+Observability labels (`job_name`, `phase_tag`) default to sensible values.
+
+## API summary
+
+The full public API is listed in [`__init__.py`](src/coding_cli_runtime/__init__.py).
+Key function groups:
+
+| Group | Functions |
+|-------|-----------|
+| Execution | `run_cli_command`, `run_cli_command_sync`, `run_interactive_session` |
+| Provider metadata | `get_provider_contract`, `get_provider_spec`, `list_provider_specs` |
+| Contract helpers | `build_env_overlay`, `resolve_config_paths`, `render_prompt`, `resolve_auth` |
+| Headless launch | `build_claude_headless_core`, `build_codex_headless_core`, `build_copilot_headless_core`, `build_gemini_headless_core` |
+| Codex batch | `build_codex_exec_spec` |
+| Failure handling | `classify_provider_failure` |
+| Session logs | `find_codex_session`, `find_claude_session` |
+| Schema | `load_schema`, `validate_payload` |
+| Utilities | `redact_text`, `build_model_id`, `normalize_path_str` |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and quality checks.
 
 ## Prerequisites
 

{coding_cli_runtime-0.2.0.dist-info → coding_cli_runtime-0.3.0.dist-info}/RECORD

@@ -1,12 +1,13 @@
-coding_cli_runtime/__init__.py,sha256=bp-A3L3Fh-2cEnAEa-bmWxaCv_7xWhY9XJNBLVwYTc8,3555
+coding_cli_runtime/__init__.py,sha256=S_dSga-xYos95nGC4yq8gQ2SvAUrpERnAFyJ-_SZDkY,3845
 coding_cli_runtime/auth.py,sha256=XP3TZINazvzKcrdgp-pcJcbG4s220dbVVPjF7ivI-wA,2284
-coding_cli_runtime/codex_cli.py,sha256=HFsA7Bd1vW9TWUZSsMANezVGbwTKxuuQZihxu9Hf9U8,2988
+coding_cli_runtime/codex_cli.py,sha256=h26tfb1Kj9LyQV19OvMV-DS4NKvdWrDPXVKGhS8lALI,3002
 coding_cli_runtime/contracts.py,sha256=teYMPDYCjL6HRwRBucJKetfZKlRnxpG82BrC1Y1OMNg,1764
 coding_cli_runtime/copilot_reasoning_baseline.json,sha256=hEIsqm03-D8T9Snn_FvbC2RD367fXGziyTK0Ajpxrmk,1649
 coding_cli_runtime/copilot_reasoning_logs.py,sha256=S2GD0zGgwVXAPe-DyJPKMR5j-EgOGlANnIt315mIWuo,2327
 coding_cli_runtime/failure_classification.py,sha256=fjGOjtQaBh6Y13gEIS7ystmadcrFKsLAN-fccBuerBs,6027
+coding_cli_runtime/headless.py,sha256=0q0L-crpIRb4A7GCOH2kyoSnyw37USGyFTzP6OOQq9Q,4186
 coding_cli_runtime/json_io.py,sha256=1RseVXV-uPWRm_-pGIUTAvhALnMAEivCX46zvlVpri0,2665
-coding_cli_runtime/provider_contracts.py,sha256=3KQqqCYiq5SC1K-Clki0S6uzoDaIYHiCnUTXV8V8_h0,14686
+coding_cli_runtime/provider_contracts.py,sha256=IgwpuF5_imwdVARzb2azKsitutahlUTN_KWZxn3Kvw0,15422
 coding_cli_runtime/provider_controls.py,sha256=2rl1XxGYFODu6LRx3bLhptgN5M_T3klx2lqT_gAAkb0,3328
 coding_cli_runtime/provider_specs.py,sha256=n9cptkPVI5sIBVuJlqE8nuTU7SyJwG8rkUF2enM_KZc,26777
 coding_cli_runtime/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
@@ -14,12 +15,12 @@ coding_cli_runtime/reasoning.py,sha256=Ggyw1K9Ry4bytzeS-Jy8jmNHVJR891zH_4jRpYAsw
 coding_cli_runtime/redaction.py,sha256=PALvJoNt7r0E_Dd3N02tCV9RI_0nPfSgoVAeaWxeLAY,559
 coding_cli_runtime/schema_validation.py,sha256=WZvl2_LkAnuxNMmpS2-vjtLqny034G9xT7wh1BZ1gwM,3929
 coding_cli_runtime/session_execution.py,sha256=U9oRrz2ORuZJzUf4WK2BS6ubCSLOHe94izg6xmn6d3E,20714
-coding_cli_runtime/session_logs.py,sha256=B3B7MB9oe829cRyLyT4GyYySTXDjHOG3TG-WqbNfRzE,3750
+coding_cli_runtime/session_logs.py,sha256=wyHld9yVydWd06jSxFSW7MwzxSbiJVLNzKN4Hh6dUkU,5689
 coding_cli_runtime/subprocess_runner.py,sha256=WqYMI6ALWFhEUySycfHXEtXuCX3m5x7s1n3Bd0TyPm0,11419
 coding_cli_runtime/schemas/normalized_run_result.v1.json,sha256=ogVKJbDFAd9dJklmp8SUkdR9L5EX1rdHGj5leJJHXGs,1110
 coding_cli_runtime/schemas/reasoning_metadata.v1.json,sha256=nQWhqp9-dlzJM18OARDUwAyaA-3-I8rETZYvkgTAnOc,467
-coding_cli_runtime-0.2.0.dist-info/licenses/LICENSE,sha256=hVIuaMVAgQkhTh44et0cpDtN3kGOZnKQ2bY1rJJw-MI,1078
-coding_cli_runtime-0.2.0.dist-info/METADATA,sha256=XaHVlmvjjdY7gu3M8EjSIgKeET1DK4FdXqOFaf-xymY,7995
-coding_cli_runtime-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-coding_cli_runtime-0.2.0.dist-info/top_level.txt,sha256=-tzjii3Qf_GTevxT5M46tITBY02R-K8Ew04hJRHOB2Y,19
-coding_cli_runtime-0.2.0.dist-info/RECORD,,
+coding_cli_runtime-0.3.0.dist-info/licenses/LICENSE,sha256=hVIuaMVAgQkhTh44et0cpDtN3kGOZnKQ2bY1rJJw-MI,1078
+coding_cli_runtime-0.3.0.dist-info/METADATA,sha256=e9518dIGTaGLay8wou9xEF2V1tjsqqPsZghRLSjIvKs,10801
+coding_cli_runtime-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+coding_cli_runtime-0.3.0.dist-info/top_level.txt,sha256=-tzjii3Qf_GTevxT5M46tITBY02R-K8Ew04hJRHOB2Y,19
+coding_cli_runtime-0.3.0.dist-info/RECORD,,