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

coding_cli_runtime/__init__.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
-
 from .auth import AuthResolution, resolve_auth
 from .codex_cli import CodexExecSpec, build_codex_exec_spec
 from .contracts import (
@@ -15,19 +13,34 @@ 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,
+    DiagnosticsContract,
     HeadlessContract,
+    IoContract,
+    OutputContract,
     PathContract,
     PromptPayload,
     PromptTransport,
     ProviderContract,
     SandboxContract,
+    SessionDiscoveryContract,
+    WorkspaceEnvValueSource,
+    WorkspaceEnvVar,
     build_env_overlay,
     get_provider_contract,
+    is_provider_installed,
     render_prompt,
     resolve_config_paths,
+    resolve_session_search_paths,
+    resolve_workspace_env,
 )
 from .provider_controls import build_model_id, resolve_provider_model_controls
 from .provider_specs import (
@@ -69,6 +82,8 @@ from .session_logs import (
 )
 from .subprocess_runner import run_cli_command, run_cli_command_sync
 
+__version__ = "0.4.0"
+
 __all__ = [
     "ApprovalContract",
     "AuthContract",
@@ -81,10 +96,13 @@ __all__ = [
     "ClaudeReasoningPolicy",
     "CliLaunchSpec",
     "ControlSpec",
+    "DiagnosticsContract",
     "ErrorCode",
     "FailureClassification",
     "HeadlessContract",
+    "IoContract",
     "ModelSpec",
+    "OutputContract",
     "PathContract",
     "PromptPayload",
     "PromptTransport",
@@ -92,12 +110,20 @@ __all__ = [
     "ProviderSpec",
     "SandboxContract",
     "SchemaValidationError",
+    "SessionDiscoveryContract",
+    "WorkspaceEnvVar",
+    "WorkspaceEnvValueSource",
     "InteractiveCliRunResult",
     "SessionProgressEvent",
     "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",
@@ -110,9 +136,9 @@ __all__ = [
     "get_gemini_model_options",
     "get_provider_contract",
     "get_provider_spec",
+    "is_provider_installed",
     "list_provider_specs",
     "build_model_id",
-    "build_codex_exec_spec",
     "classify_provider_failure",
     "load_schema",
     "render_prompt",
@@ -120,6 +146,8 @@ __all__ = [
     "resolve_claude_reasoning_policy",
     "resolve_config_paths",
     "resolve_provider_model_controls",
+    "resolve_session_search_paths",
+    "resolve_workspace_env",
     "redact_text",
     "claude_project_key",
     "find_claude_session",

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

@@ -5,7 +5,8 @@ config paths, and headless launch conventions. It exposes frozen dataclasses
 that consumers can read selectively — no obligation to use the full structure.
 
 Public stable API:
-    get_provider_contract, build_env_overlay, resolve_config_paths, render_prompt
+    get_provider_contract, build_env_overlay, resolve_config_paths, render_prompt,
+    resolve_workspace_env, resolve_session_search_paths, is_provider_installed
 
 Internal (not exported from __init__):
     _build_non_interactive_run
@@ -13,8 +14,10 @@ Internal (not exported from __init__):
 
 from __future__ import annotations
 
+import shutil
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Literal, TypeAlias
 
 from .contracts import AuthMode
 
@@ -105,6 +108,51 @@ class HeadlessContract:
     default_stream_mode: str | None
 
 
+@dataclass(frozen=True)
+class OutputContract:
+    """How the CLI delivers structured output."""
+
+    format_flag: str | None
+    supported_formats: tuple[str, ...]
+    default_format: str | None
+    output_path_flag: str | None
+    schema_path_flag: str | None
+
+
+WorkspaceEnvValueSource: TypeAlias = Literal["execution_dir", "workspace_root"]
+
+
+@dataclass(frozen=True)
+class WorkspaceEnvVar:
+    """An environment variable expected by the provider CLI."""
+
+    name: str
+    value_source: WorkspaceEnvValueSource
+
+
+@dataclass(frozen=True)
+class IoContract:
+    """Provider-specific I/O conventions beyond prompt transport."""
+
+    file_reference_prefix: str | None
+    workspace_env_vars: tuple[WorkspaceEnvVar, ...]
+
+
+@dataclass(frozen=True)
+class SessionDiscoveryContract:
+    """Where session logs live and how to find them."""
+
+    session_roots: tuple[str, ...]
+    session_glob: str
+
+
+@dataclass(frozen=True)
+class DiagnosticsContract:
+    """Where provider diagnostic logs live."""
+
+    log_glob: str
+
+
 @dataclass(frozen=True)
 class ProviderContract:
     """Structured metadata about a provider CLI.
@@ -118,6 +166,10 @@ class ProviderContract:
     auth: AuthContract
     paths: PathContract
     headless: HeadlessContract
+    output: OutputContract
+    io: IoContract
+    session_discovery: SessionDiscoveryContract | None
+    diagnostics: DiagnosticsContract | None
     notes: tuple[str, ...]
 
 
@@ -178,6 +230,22 @@ _CLAUDE_CONTRACT = ProviderContract(
         stream_modes=None,
         default_stream_mode=None,
     ),
+    output=OutputContract(
+        format_flag="--output-format",
+        supported_formats=("text", "json", "stream-json"),
+        default_format="text",
+        output_path_flag=None,
+        schema_path_flag=None,
+    ),
+    io=IoContract(
+        file_reference_prefix=None,
+        workspace_env_vars=(),
+    ),
+    session_discovery=SessionDiscoveryContract(
+        session_roots=("projects",),
+        session_glob="*/conversation.jsonl",
+    ),
+    diagnostics=None,
     notes=(),
 )
 
@@ -217,6 +285,22 @@ _CODEX_CONTRACT = ProviderContract(
         stream_modes=None,
         default_stream_mode=None,
     ),
+    output=OutputContract(
+        format_flag=None,
+        supported_formats=("json",),
+        default_format="json",
+        output_path_flag="-o",
+        schema_path_flag="--output-schema",
+    ),
+    io=IoContract(
+        file_reference_prefix=None,
+        workspace_env_vars=(),
+    ),
+    session_discovery=SessionDiscoveryContract(
+        session_roots=("sessions", "archived_sessions"),
+        session_glob="*.jsonl",
+    ),
+    diagnostics=None,
     notes=(
         "codex exec defaults to a read-only sandbox in non-interactive mode; "
         "use --sandbox danger-full-access for write access.",
@@ -258,9 +342,32 @@ _GEMINI_CONTRACT = ProviderContract(
         stream_modes=None,
         default_stream_mode=None,
     ),
+    output=OutputContract(
+        format_flag=None,
+        supported_formats=(),
+        default_format=None,
+        output_path_flag=None,
+        schema_path_flag=None,
+    ),
+    io=IoContract(
+        file_reference_prefix="@",
+        workspace_env_vars=(
+            WorkspaceEnvVar(
+                name="GEMINI_CLI_IDE_WORKSPACE_PATH",
+                value_source="execution_dir",
+            ),
+        ),
+    ),
+    session_discovery=SessionDiscoveryContract(
+        session_roots=("tmp",),
+        session_glob="*/chats/session-*.json",
+    ),
+    diagnostics=None,
     notes=(
         'Gemini requires --prompt "" to activate headless mode; '
         "the real prompt is delivered on stdin.",
+        "Gemini output format is prompt-directed, not CLI-flag-driven.",
+        "File references in prompts use @filename syntax.",
     ),
 )
 
@@ -295,6 +402,24 @@ _COPILOT_CONTRACT = ProviderContract(
         stream_modes=("on", "off"),
         default_stream_mode="on",
     ),
+    output=OutputContract(
+        format_flag=None,
+        supported_formats=("markdown",),
+        default_format="markdown",
+        output_path_flag="--share",
+        schema_path_flag=None,
+    ),
+    io=IoContract(
+        file_reference_prefix=None,
+        workspace_env_vars=(),
+    ),
+    session_discovery=SessionDiscoveryContract(
+        session_roots=("session-state",),
+        session_glob="*/events.jsonl",
+    ),
+    diagnostics=DiagnosticsContract(
+        log_glob="logs/process-*.log",
+    ),
     notes=(
         "Copilot default auth is CLI login (api_key_env_var is None). "
         "BYOK is available via COPILOT_PROVIDER_API_KEY.",
@@ -350,6 +475,33 @@ def build_env_overlay(
     return overlay
 
 
+def resolve_workspace_env(
+    contract: ProviderContract,
+    execution_dir: str | Path,
+    *,
+    workspace_root: str | Path | None = None,
+) -> dict[str, str]:
+    """Resolve provider workspace env vars from contract metadata."""
+    resolved: dict[str, str] = {}
+    execution_dir_str = str(Path(execution_dir).expanduser())
+    workspace_root_str = None
+    if workspace_root is not None:
+        workspace_root_str = str(Path(workspace_root).expanduser())
+
+    for item in contract.io.workspace_env_vars:
+        if item.value_source == "execution_dir":
+            resolved[item.name] = execution_dir_str
+            continue
+        if item.value_source == "workspace_root":
+            if workspace_root_str is None:
+                raise ValueError(f"{item.name} requires workspace_root, but none was provided")
+            resolved[item.name] = workspace_root_str
+            continue
+        raise ValueError(f"Unknown workspace env value source: {item.value_source!r}")
+
+    return resolved
+
+
 def resolve_config_paths(
     contract: ProviderContract,
     *,
@@ -366,6 +518,23 @@ def resolve_config_paths(
     return host, host
 
 
+def resolve_session_search_paths(
+    contract: ProviderContract,
+    *,
+    config_dir: str | Path | None = None,
+) -> tuple[Path, ...]:
+    """Expand contract session roots into concrete host paths."""
+    discovery = contract.session_discovery
+    if discovery is None:
+        return ()
+    base_dir = (
+        Path(config_dir).expanduser()
+        if config_dir is not None
+        else Path(contract.paths.config_dir).expanduser()
+    )
+    return tuple(base_dir / root for root in discovery.session_roots)
+
+
 def render_prompt(
     transport: PromptTransport,
     prompt: str,
@@ -387,6 +556,12 @@ def render_prompt(
     raise ValueError(f"Unknown prompt delivery mode: {transport.delivery!r}")
 
 
+def is_provider_installed(provider_id: str) -> bool:
+    """Return whether the provider CLI binary is available on PATH."""
+    contract = get_provider_contract(provider_id)
+    return shutil.which(contract.binary) is not None
+
+
 # ---------------------------------------------------------------------------
 # Private builder (internal convenience, not public API)
 # ---------------------------------------------------------------------------
@@ -406,47 +581,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])
+    """Build a non-interactive CLI run spec. Internal convenience.
 
-    # Git repo bypass
-    if h.requires_git_repo and h.skip_git_repo_flag:
-        cmd.append(h.skip_git_repo_flag)
-
-    # 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.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-cli-runtime
-Version: 0.2.0
+Version: 0.4.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,
 )
@@ -148,6 +152,44 @@ else:
 Works for all four providers. Recognizes auth failures, rate limits,
 network transients, and other provider-specific error patterns.
 
+### Common integration tasks
+
+#### Check whether a provider CLI is installed
+
+```python
+from coding_cli_runtime import is_provider_installed
+
+if not is_provider_installed("claude"):
+    raise RuntimeError("Claude Code is not available on PATH")
+```
+
+This is intentionally minimal: it checks whether the provider binary exists on
+PATH. Deeper CLI drift validation belongs in maintainer tooling, not the
+runtime API.
+
+#### Resolve workspace env vars and session search paths
+
+```python
+from coding_cli_runtime import (
+    get_provider_contract,
+    resolve_session_search_paths,
+    resolve_workspace_env,
+)
+
+gemini = get_provider_contract("gemini")
+
+# Derive provider-specific workspace env vars from contract metadata
+env = resolve_workspace_env(gemini, "/tmp/run-dir")
+# {"GEMINI_CLI_IDE_WORKSPACE_PATH": "/tmp/run-dir"}
+
+# Expand concrete host paths for session log searches
+paths = resolve_session_search_paths(gemini)
+# (Path.home() / ".gemini" / "tmp",)
+```
+
+Use these helpers when you want the contract facts turned into concrete
+filesystem/env values without rebuilding the same glue logic in each consumer.
+
 ### Look up provider contract metadata
 
 ```python
@@ -175,11 +217,75 @@ payload = render_prompt(contract.headless.prompt, "Fix the bug")
 ```
 
 `ProviderContract` is structured as nested sub-contracts
-(`AuthContract`, `PathContract`, `HeadlessContract`) so consumers
+(`AuthContract`, `PathContract`, `HeadlessContract`, `OutputContract`,
+`IoContract`, `SessionDiscoveryContract`, `DiagnosticsContract`) so consumers
 can drill into whichever aspect they need. This is reference metadata,
-not a command-construction control plane — consumers keep their own
+not a command-construction control plane — callers keep their own
 command assembly and adopt contract fields selectively.
 
+### Query provider I/O conventions
+
+```python
+from coding_cli_runtime import get_provider_contract
+
+gemini = get_provider_contract("gemini")
+
+# Workspace env vars with value semantics
+for wev in gemini.io.workspace_env_vars:
+    print(f"{wev.name} = {wev.value_source}")
+    # GEMINI_CLI_IDE_WORKSPACE_PATH = execution_dir
+
+# Session discovery (where session logs live)
+sd = gemini.session_discovery
+print(sd.session_roots)  # ("tmp",)
+print(sd.session_glob)   # "*/chats/session-*.json"
+
+# Output format support
+codex = get_provider_contract("codex")
+print(codex.output.output_path_flag)    # "-o"
+print(codex.output.schema_path_flag)    # "--output-schema"
+
+# Diagnostics (Copilot only)
+copilot = get_provider_contract("copilot")
+if copilot.diagnostics:
+    print(copilot.diagnostics.log_glob)  # "logs/process-*.log"
+```
+
+`WorkspaceEnvVar.value_source` uses a closed vocabulary:
+`"execution_dir"` or `"workspace_root"`.
+
+### 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 |
@@ -188,14 +294,55 @@ command assembly and adopt contract fields selectively.
 | `CliRunResult` | Result: returncode, stdout/stderr, duration, error code |
 | `ErrorCode` | `none` · `spawn_failed` · `timed_out` · `non_zero_exit` |
 | `ProviderSpec` | Provider catalog entry with models, controls, defaults |
-| `ProviderContract` | Structured provider CLI metadata (auth, paths, headless launch) |
+| `ProviderContract` | Structured provider CLI metadata (auth, paths, headless, I/O, sessions) |
+| `WorkspaceEnvVar` | Env var with value-source semantics (`execution_dir`, `workspace_root`) |
 | `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.
+Other parameters have sensible defaults.
+
+## 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`, `resolve_workspace_env`, `resolve_session_search_paths` |
+| 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` |
+| Installation check | `is_provider_installed` |
+| 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.4.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=06_cwfOA9AMqD6oj5H7_uGj1405leIL6eYc_vCFOREg,4321
 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=-UhDva-gAWLTgk1ZFxo2gKNpb5GL6Cba68yJR9YB47w,20630
 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.4.0.dist-info/licenses/LICENSE,sha256=hVIuaMVAgQkhTh44et0cpDtN3kGOZnKQ2bY1rJJw-MI,1078
+coding_cli_runtime-0.4.0.dist-info/METADATA,sha256=wh9K2YDO1-741eS4nRnSwDY4t0LBpLh9eOb9QtgMzgE,13099
+coding_cli_runtime-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+coding_cli_runtime-0.4.0.dist-info/top_level.txt,sha256=-tzjii3Qf_GTevxT5M46tITBY02R-K8Ew04hJRHOB2Y,19
+coding_cli_runtime-0.4.0.dist-info/RECORD,,