coding-cli-runtime 0.3.0__tar.gz → 0.4.0__tar.gz

coding_cli_runtime-0.4.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-04-09
+
+### Added
+- `OutputContract`, `IoContract`, `SessionDiscoveryContract`,
+  `DiagnosticsContract` sub-contracts on `ProviderContract`, with data
+  populated for all four providers.
+- `WorkspaceEnvVar` structured type with `name` + `value_source` semantics
+  (replaces bare env-var name strings in `IoContract.workspace_env_vars`).
+- `WorkspaceEnvValueSource` — closed vocabulary (`"execution_dir"` /
+  `"workspace_root"`) for `WorkspaceEnvVar.value_source`.
+- `resolve_workspace_env()` — turns `IoContract.workspace_env_vars` into a
+  concrete env overlay from an execution directory.
+- `resolve_session_search_paths()` — expands `SessionDiscoveryContract`
+  roots into concrete host paths.
+- `is_provider_installed()` — checks whether a provider CLI binary is on
+  PATH.
+- README sections: "Query provider I/O conventions" and "Common integration
+  tasks" with copy-pasteable examples.
+- `WorkspaceEnvVar` added to key-types table in README.
+
+### Changed
+- Gemini `session_glob` tightened from `"*.json"` to `"*/chats/session-*.json"`
+  to match the real `tmp/{hash}/chats/session-*.json` layout.
+- Claude `session_glob` tightened from `"*.jsonl"` to
+  `"*/conversation.jsonl"` to match per-project subdirectory structure.
+
+## [0.3.0] - 2026-04-09
+
+### Added
+- Per-provider headless launch helpers: `build_claude_headless_core()`,
+  `build_codex_headless_core()`, `build_copilot_headless_core()`,
+  `build_gemini_headless_core()`. These emit the standard non-interactive
+  flags for each provider; callers append app-specific tails.
+- Session log discovery section in README.
+- API summary table in README.
+
+### Changed
+- `build_codex_exec_spec()` now delegates to `build_codex_headless_core()`.
+  `full_auto` and `skip_git_repo_check` params preserved.
+- README rewritten with task-oriented examples, `run_interactive_session`
+  usage, `uv add` install, and API summary.
+
+## [0.2.0] - 2026-04-08
+
+### Added
+- `ProviderContract` API — structured, nested metadata for all four provider
+  CLIs (Claude, Codex, Gemini, Copilot). Composed of `AuthContract`,
+  `PathContract`, `HeadlessContract`, `PromptTransport`, `ApprovalContract`,
+  `SandboxContract`.
+- `get_provider_contract(provider_id)` — returns structured contract for a
+  provider.
+- `build_env_overlay(contract, api_key, base_url)` — builds provider-specific
+  env var overlay from contract metadata.
+- `resolve_config_paths(contract, containerized)` — resolves host and container
+  config directory paths.
+- `render_prompt(transport, prompt)` — resolves prompt delivery into argv args +
+  stdin text based on provider transport mode.
+- `PromptPayload` dataclass for resolved prompt delivery.
+- `resolve_auth()` — resolves provider auth status from environment.
+- `__version__` attribute.
+- `CONTRIBUTING.md` with development setup and quality checks.
+
+### Changed
+- `run_interactive_session()` observability kwargs (`job_name`, `phase_tag`)
+  now have sensible defaults so callers don't need to supply them.
+- `CliRunResult.command` type widened from `tuple[str, ...]` to `Sequence[str]`.
+- Provider model catalogs resolved with three-tier fallback: user override
+  file > live CLI discovery > hardcoded fallback.
+
+### Fixed
+- Copilot BYOK (`COPILOT_PROVIDER_API_KEY`) now discoverable via contract
+  but not reported as "required" in `resolve_auth()` — BYOK is opt-in.
+
+## [0.1.0] - 2026-04-07
+
+### Added
+- Provider metadata and controls for Claude, Codex, Copilot, and Gemini CLIs.
+- Shared request/result contracts (`CliRunRequest`, `CliRunResult`, `CliLaunchSpec`).
+- Schema loading and payload validation (`load_schema`, `validate_payload`).
+- Synchronous and asynchronous subprocess execution helpers.
+- Interactive session execution with transcript mirroring.
+- Session log discovery and parsing utilities.
+- Claude reasoning policy resolution.
+- Log redaction helpers.
+- Copilot reasoning log parsing and classification.
+- PEP 561 `py.typed` markers for both `coding_cli_runtime` and `shared_cli_runtime`.
+- Packaged JSON schemas and Copilot reasoning baseline data.
+- Playground knowledge base with probing guides and experiment templates.

{coding_cli_runtime-0.3.0 → coding_cli_runtime-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-cli-runtime
-Version: 0.3.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
@@ -152,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
@@ -179,11 +217,43 @@ 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
@@ -224,7 +294,8 @@ files matching the working directory and time window.
 | `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 long-lived CLI sessions
@@ -249,7 +320,7 @@ result = await run_interactive_session(
 ```
 
 Only `cmd_parts`, `cwd`, `stdin_text`, and `logger` are required.
-Observability labels (`job_name`, `phase_tag`) default to sensible values.
+Other parameters have sensible defaults.
 
 ## API summary
 
@@ -260,10 +331,11 @@ Key function groups:
 |-------|-----------|
 | 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` |
+| 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` |

{coding_cli_runtime-0.3.0 → coding_cli_runtime-0.4.0}/README.md

@@ -126,6 +126,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
@@ -153,11 +191,43 @@ 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
@@ -198,7 +268,8 @@ files matching the working directory and time window.
 | `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 long-lived CLI sessions
@@ -223,7 +294,7 @@ result = await run_interactive_session(
 ```
 
 Only `cmd_parts`, `cwd`, `stdin_text`, and `logger` are required.
-Observability labels (`job_name`, `phase_tag`) default to sensible values.
+Other parameters have sensible defaults.
 
 ## API summary
 
@@ -234,10 +305,11 @@ Key function groups:
 |-------|-----------|
 | 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` |
+| 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` |

{coding_cli_runtime-0.3.0 → coding_cli_runtime-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coding-cli-runtime"
-version = "0.3.0"
+version = "0.4.0"
 description = "Reusable CLI runtime primitives for provider-backed automation workflows"
 readme = {file = "README.md", content-type = "text/markdown"}
 license = "MIT"
@@ -94,7 +94,7 @@ disallow_untyped_defs = false
 warn_return_any = false
 
 [tool.bumpversion]
-current_version = "0.3.0"
+current_version = "0.4.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true

{coding_cli_runtime-0.3.0 → coding_cli_runtime-0.4.0}/src/coding_cli_runtime/__init__.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.3.0"
-
 from .auth import AuthResolution, resolve_auth
 from .codex_cli import CodexExecSpec, build_codex_exec_spec
 from .contracts import (
@@ -24,16 +22,25 @@ from .headless import (
 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 (
@@ -75,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",
@@ -87,10 +96,13 @@ __all__ = [
     "ClaudeReasoningPolicy",
     "CliLaunchSpec",
     "ControlSpec",
+    "DiagnosticsContract",
     "ErrorCode",
     "FailureClassification",
     "HeadlessContract",
+    "IoContract",
     "ModelSpec",
+    "OutputContract",
     "PathContract",
     "PromptPayload",
     "PromptTransport",
@@ -98,6 +110,9 @@ __all__ = [
     "ProviderSpec",
     "SandboxContract",
     "SchemaValidationError",
+    "SessionDiscoveryContract",
+    "WorkspaceEnvVar",
+    "WorkspaceEnvValueSource",
     "InteractiveCliRunResult",
     "SessionProgressEvent",
     "SessionRetryDecision",
@@ -121,6 +136,7 @@ __all__ = [
     "get_gemini_model_options",
     "get_provider_contract",
     "get_provider_spec",
+    "is_provider_installed",
     "list_provider_specs",
     "build_model_id",
     "classify_provider_failure",
@@ -130,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-0.3.0 → coding_cli_runtime-0.4.0}/src/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)
 # ---------------------------------------------------------------------------

{coding_cli_runtime-0.3.0 → coding_cli_runtime-0.4.0}/src/coding_cli_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-cli-runtime
-Version: 0.3.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
@@ -152,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
@@ -179,11 +217,43 @@ 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
@@ -224,7 +294,8 @@ files matching the working directory and time window.
 | `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 long-lived CLI sessions
@@ -249,7 +320,7 @@ result = await run_interactive_session(
 ```
 
 Only `cmd_parts`, `cwd`, `stdin_text`, and `logger` are required.
-Observability labels (`job_name`, `phase_tag`) default to sensible values.
+Other parameters have sensible defaults.
 
 ## API summary
 
@@ -260,10 +331,11 @@ Key function groups:
 |-------|-----------|
 | 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` |
+| 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` |

{coding_cli_runtime-0.3.0 → coding_cli_runtime-0.4.0}/src/coding_cli_runtime.egg-info/SOURCES.txt

@@ -37,4 +37,6 @@ tests/test_playground_probe_smoke.py
 tests/test_provider_catalog_resolution.py
 tests/test_provider_contracts.py
 tests/test_runtime_parity.py
-tests/test_stage2_tier1.py
+tests/test_stage2_tier1.py
+tests/test_stage3_io_contracts.py
+tests/test_stage4_helpers.py

{coding_cli_runtime-0.3.0 → coding_cli_runtime-0.4.0}/tests/test_stage2_tier1.py

@@ -1,4 +1,4 @@
-"""Tests for Stage 2 Tier 1 extractions: headless cores, scan_session_dir."""
+"""Tests for headless cores and scan_session_dir."""
 
 from __future__ import annotations
 

coding_cli_runtime-0.4.0/tests/test_stage3_io_contracts.py

@@ -0,0 +1,119 @@
+"""Tests for provider I/O contract types."""
+
+from __future__ import annotations
+
+from typing import get_args, get_type_hints
+
+from coding_cli_runtime.provider_contracts import (
+    WorkspaceEnvValueSource,
+    WorkspaceEnvVar,
+    get_provider_contract,
+)
+
+ALL_PROVIDERS = ("claude", "codex", "gemini", "copilot")
+
+
+# ── OutputContract ────────────────────────────────────────────────────
+
+
+class TestOutputContract:
+    def test_claude_has_format_flag(self) -> None:
+        c = get_provider_contract("claude")
+        assert c.output.format_flag == "--output-format"
+        assert "text" in c.output.supported_formats
+        assert "json" in c.output.supported_formats
+        assert "stream-json" in c.output.supported_formats
+        assert c.output.default_format == "text"
+
+    def test_codex_has_output_path_flag(self) -> None:
+        c = get_provider_contract("codex")
+        assert c.output.output_path_flag == "-o"
+        assert c.output.schema_path_flag == "--output-schema"
+        assert c.output.format_flag is None
+
+    def test_gemini_has_no_output_flags(self) -> None:
+        c = get_provider_contract("gemini")
+        assert c.output.format_flag is None
+        assert c.output.output_path_flag is None
+        assert len(c.output.supported_formats) == 0
+
+    def test_copilot_has_share_flag(self) -> None:
+        c = get_provider_contract("copilot")
+        assert c.output.output_path_flag == "--share"
+        assert c.output.format_flag is None
+        assert "markdown" in c.output.supported_formats
+
+
+# ── IoContract ────────────────────────────────────────────────────────
+
+
+class TestIoContract:
+    def test_workspace_env_value_source_is_closed_vocabulary(self) -> None:
+        hints = get_type_hints(WorkspaceEnvVar)
+        assert hints["value_source"] == WorkspaceEnvValueSource
+        assert get_args(WorkspaceEnvValueSource) == ("execution_dir", "workspace_root")
+
+    def test_gemini_file_reference_prefix(self) -> None:
+        c = get_provider_contract("gemini")
+        assert c.io.file_reference_prefix == "@"
+
+    def test_other_providers_no_file_reference(self) -> None:
+        for pid in ("claude", "codex", "copilot"):
+            c = get_provider_contract(pid)
+            assert c.io.file_reference_prefix is None
+
+    def test_gemini_workspace_env_var(self) -> None:
+        c = get_provider_contract("gemini")
+        assert len(c.io.workspace_env_vars) == 1
+        wev = c.io.workspace_env_vars[0]
+        assert wev.name == "GEMINI_CLI_IDE_WORKSPACE_PATH"
+        assert wev.value_source == "execution_dir"
+
+    def test_other_providers_no_workspace_env_vars(self) -> None:
+        for pid in ("claude", "codex", "copilot"):
+            c = get_provider_contract(pid)
+            assert c.io.workspace_env_vars == ()
+
+
+# ── SessionDiscoveryContract ──────────────────────────────────────────
+
+
+class TestSessionDiscoveryContract:
+    def test_all_providers_have_session_discovery(self) -> None:
+        for pid in ALL_PROVIDERS:
+            c = get_provider_contract(pid)
+            assert c.session_discovery is not None
+
+    def test_codex_session_roots(self) -> None:
+        c = get_provider_contract("codex")
+        assert "sessions" in c.session_discovery.session_roots
+        assert "archived_sessions" in c.session_discovery.session_roots
+
+    def test_claude_session_glob(self) -> None:
+        c = get_provider_contract("claude")
+        assert c.session_discovery.session_glob == "*/conversation.jsonl"
+
+    def test_copilot_session_discovery(self) -> None:
+        c = get_provider_contract("copilot")
+        assert "session-state" in c.session_discovery.session_roots
+        assert "events.jsonl" in c.session_discovery.session_glob
+
+    def test_gemini_session_discovery(self) -> None:
+        c = get_provider_contract("gemini")
+        assert "tmp" in c.session_discovery.session_roots
+        assert c.session_discovery.session_glob == "*/chats/session-*.json"
+
+
+# ── DiagnosticsContract ───────────────────────────────────────────────
+
+
+class TestDiagnosticsContract:
+    def test_copilot_has_diagnostics(self) -> None:
+        c = get_provider_contract("copilot")
+        assert c.diagnostics is not None
+        assert "process-*.log" in c.diagnostics.log_glob
+
+    def test_other_providers_no_diagnostics(self) -> None:
+        for pid in ("claude", "codex", "gemini"):
+            c = get_provider_contract(pid)
+            assert c.diagnostics is None

coding_cli_runtime-0.4.0/tests/test_stage4_helpers.py

@@ -0,0 +1,105 @@
+"""Tests for consumer-UX helpers."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+
+import pytest
+
+from coding_cli_runtime import (
+    IoContract,
+    WorkspaceEnvVar,
+    get_provider_contract,
+    is_provider_installed,
+    resolve_session_search_paths,
+    resolve_workspace_env,
+)
+from coding_cli_runtime import provider_contracts as provider_contracts_mod
+
+
+class TestResolveWorkspaceEnv:
+    def test_gemini_workspace_env_uses_execution_dir(self) -> None:
+        contract = get_provider_contract("gemini")
+
+        env = resolve_workspace_env(contract, "/tmp/run-dir")
+
+        assert env == {"GEMINI_CLI_IDE_WORKSPACE_PATH": "/tmp/run-dir"}
+
+    def test_provider_with_no_workspace_env_vars_returns_empty_dict(self) -> None:
+        contract = get_provider_contract("claude")
+
+        env = resolve_workspace_env(contract, "/tmp/run-dir")
+
+        assert env == {}
+
+    def test_workspace_root_value_source_requires_workspace_root(self) -> None:
+        base = get_provider_contract("claude")
+        contract = replace(
+            base,
+            io=IoContract(
+                file_reference_prefix=None,
+                workspace_env_vars=(
+                    WorkspaceEnvVar(
+                        name="TEST_WORKSPACE_ROOT",
+                        value_source="workspace_root",
+                    ),
+                ),
+            ),
+        )
+
+        with pytest.raises(ValueError, match="requires workspace_root"):
+            resolve_workspace_env(contract, "/tmp/execution-dir")
+
+        env = resolve_workspace_env(
+            contract,
+            "/tmp/execution-dir",
+            workspace_root="/tmp/workspace-root",
+        )
+        assert env == {"TEST_WORKSPACE_ROOT": "/tmp/workspace-root"}
+
+
+class TestResolveSessionSearchPaths:
+    def test_gemini_defaults_to_config_dir_tmp_root(self) -> None:
+        contract = get_provider_contract("gemini")
+
+        paths = resolve_session_search_paths(contract)
+
+        assert paths == (Path("~/.gemini").expanduser() / "tmp",)
+
+    def test_defaults_to_contract_config_dir(self) -> None:
+        contract = get_provider_contract("claude")
+
+        paths = resolve_session_search_paths(contract)
+
+        assert paths == (Path("~/.claude").expanduser() / "projects",)
+
+    def test_honors_config_dir_override(self) -> None:
+        contract = get_provider_contract("codex")
+
+        paths = resolve_session_search_paths(contract, config_dir="/tmp/codex-config")
+
+        assert paths == (
+            Path("/tmp/codex-config") / "sessions",
+            Path("/tmp/codex-config") / "archived_sessions",
+        )
+
+    def test_returns_empty_tuple_when_session_discovery_is_none(self) -> None:
+        base = get_provider_contract("copilot")
+        contract = replace(base, session_discovery=None)
+
+        paths = resolve_session_search_paths(contract)
+
+        assert paths == ()
+
+
+class TestIsProviderInstalled:
+    def test_returns_true_when_binary_is_found(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setattr(provider_contracts_mod.shutil, "which", lambda _: "/usr/bin/claude")
+
+        assert is_provider_installed("claude") is True
+
+    def test_returns_false_when_binary_is_missing(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setattr(provider_contracts_mod.shutil, "which", lambda _: None)
+
+        assert is_provider_installed("copilot") is False

coding_cli_runtime-0.3.0/CHANGELOG.md

@@ -1,101 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/).
-
-## [Unreleased]
-
-## [0.3.0] - 2026-04-09
-
-### Added
-- **Headless launch core helpers** — per-provider arg renderers derived from
-  `ProviderContract.headless`: `build_claude_headless_core()`,
-  `build_codex_headless_core()`, `build_copilot_headless_core()`,
-  `build_gemini_headless_core()`. All consumers (app-generation, feather,
-  codex_cli, provider_contracts builder) now delegate to these.
-- `scan_session_dir()` — generic directory-scanning primitive for session log
-  discovery with `extract_fn` callback (internal, not in public `__all__`).
-- Session log discovery section in README.
-- API summary table in README.
-- 27 new Stage 2 tests for headless cores, builder delegation, and
-  `scan_session_dir`.
-
-### Changed
-- `build_codex_exec_spec()` now delegates to `build_codex_headless_core()`.
-  `full_auto` and `skip_git_repo_check` params preserved and passed through.
-- `_build_non_interactive_run()` now delegates to per-provider headless core
-  helpers instead of assembling flags inline.
-- Feather `report_data.py` and `report_sections.py` use headless core helpers
-  with fallback for environments without `coding_cli_runtime`.
-- Feather `generate_report.py` Codex session discovery replaced with
-  `find_codex_session()` from `coding_cli_runtime`.
-- App-generation `claude_impl.py`, `copilot_impl.py`, `gemini_impl.py`
-  `build_command()` functions delegate to headless core helpers.
-- Dead headless opt-out flags removed from Copilot (`--allow-all`, `--ask-user`,
-  `--use-custom-instructions`) and Gemini (`--auto-approve`) CLI specs —
-  these were never used in batch runs and are now handled by the headless core.
-- README rewritten: user-action feature list, `run_interactive_session` example,
-  `uv add` install, API summary, Contributing link, session log discovery.
-
-## [0.2.0] - 2026-04-08
-
-### Added
-- **ProviderContract API** — structured, nested metadata for all four provider CLIs
-  (Claude, Codex, Gemini, Copilot). Composed of `AuthContract`, `PathContract`,
-  `HeadlessContract`, `PromptTransport`, `ApprovalContract`, `SandboxContract`.
-- `get_provider_contract(provider_id)` — returns structured contract for a provider.
-- `build_env_overlay(contract, api_key, base_url)` — builds provider-specific env
-  var overlay from contract metadata.
-- `resolve_config_paths(contract, containerized)` — resolves host and container
-  config directory paths.
-- `render_prompt(transport, prompt)` — resolves prompt delivery into argv args +
-  stdin text based on provider transport mode.
-- `PromptPayload` dataclass for resolved prompt delivery.
-- `__version__` attribute in `coding_cli_runtime`.
-- `CONTRIBUTING.md`, `MANIFEST.in`, `.pre-commit-config.yaml`.
-- PyPI / Python / Build / License badges in `README.md`.
-- `bump-my-version` configuration syncing `pyproject.toml` and `__init__.py`.
-- `ruff`, `mypy` (strict), and `pytest-cov` added to dev dependencies.
-- CI quality gates: ruff check, ruff format, mypy, pytest-cov.
-- README section documenting the new ProviderContract API with examples.
-- 75 new tests for provider contracts, helpers, internal builder, failure
-  classification, codex_cli, schema validation (including nested), reasoning,
-  redaction, json_io, provider_controls, and auth. Package coverage 47% → 62%.
-
-### Changed
-- Consolidated `shared_cli_runtime` into `coding_cli_runtime`. The package now
-  ships a single top-level package; the `shared_cli_runtime` directory is removed.
-- `MANIFEST.in` and docs updated to reference `coding_cli_runtime` paths.
-- `run_interactive_session()` observability kwargs (`provider_label`, `job_name`,
-  `phase_tag`, `process_label`, `timeout_seconds`) now have sensible defaults so
-  external callers don't need to supply internal batch-system labels.
-- Provider model catalogs are now resolved with a three-tier fallback:
-  user override file > live CLI discovery > hardcoded fallback.
-- `auth.py`: `_PROVIDER_ENV_HINTS` now derived from `provider_contracts.py`
-  (single source of truth for auth env var names).
-- `CliRunResult.command` type widened from `tuple[str, ...]` to `Sequence[str]`.
-- Publish workflow path corrected (`shared-cli-runtime` → `coding-cli-runtime`).
-
-### Fixed
-- mypy strict compliance: return-type annotations, per-module overrides.
-- ruff lint and format compliance across all source and test files.
-- Copilot BYOK (`COPILOT_PROVIDER_API_KEY`) now discoverable via contract
-  but not reported as "required" in `resolve_auth()` — BYOK is opt-in.
-
-## [0.1.0] - 2026-04-07
-
-### Added
-- Initial extraction from `llm-eval` monorepo.
-- Provider metadata and controls for Claude, Codex, Copilot, and Gemini CLIs.
-- Shared request/result contracts (`CliRunRequest`, `CliRunResult`, `CliLaunchSpec`).
-- Schema loading and payload validation (`load_schema`, `validate_payload`).
-- Synchronous and asynchronous subprocess execution helpers.
-- Interactive session execution with transcript mirroring.
-- Session log discovery and parsing utilities.
-- Claude reasoning policy resolution.
-- Log redaction helpers.
-- Copilot reasoning log parsing and classification.
-- PEP 561 `py.typed` markers for both `coding_cli_runtime` and `shared_cli_runtime`.
-- Packaged JSON schemas and Copilot reasoning baseline data.
-- Playground knowledge base with probing guides and experiment templates.