coding-cli-runtime 0.2.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.2.0 → coding_cli_runtime-0.4.0}/PKG-INFO

@@ -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.4.0/README.md

@@ -0,0 +1,333 @@
+# coding-cli-runtime
+
+[![PyPI](https://img.shields.io/pypi/v/coding-cli-runtime)](https://pypi.org/project/coding-cli-runtime/)
+[![Python](https://img.shields.io/pypi/pyversions/coding-cli-runtime)](https://pypi.org/project/coding-cli-runtime/)
+[![Build](https://github.com/pj-ms/llm-eval/actions/workflows/ci.yml/badge.svg)](https://github.com/pj-ms/llm-eval/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/coding-cli-runtime)](LICENSE)
+
+A Python library for orchestrating LLM coding agent CLIs — [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), and [GitHub Copilot](https://docs.github.com/en/copilot).
+
+These CLIs each have different invocation patterns, output formats, error
+shapes, and timeout behaviors. This library normalizes all of that behind
+a common `CliRunRequest` → `CliRunResult` contract, so your automation
+code doesn't need provider-specific subprocess handling.
+
+**What it does (and why not just `subprocess.run`):**
+
+- 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+.
+
+## Examples
+
+### Execute a provider CLI
+
+```python
+import asyncio
+from pathlib import Path
+from coding_cli_runtime import CliRunRequest, run_cli_command
+
+request = CliRunRequest(
+    cmd_parts=("codex", "--model", "gpt-5.4", "--quiet", "exec", "fix the tests"),
+    cwd=Path("/tmp/my-project"),
+    timeout_seconds=120,
+)
+result = asyncio.run(run_cli_command(request))
+
+print(result.returncode)        # 0
+print(result.error_code)        # "none"
+print(result.duration_seconds)  # 14.2
+print(result.stdout_text[:200])
+```
+
+Swap `codex` for `claude`, `gemini`, or `copilot` — the request/result
+shape stays the same. A synchronous variant `run_cli_command_sync` is also
+available.
+
+### Pick a model from the provider catalog
+
+```python
+from coding_cli_runtime import get_provider_spec
+
+codex = get_provider_spec("codex")
+print(codex.default_model)   # "gpt-5.3-codex"
+print(codex.model_source)    # "codex_cli_cache", "override", or "code"
+
+for model in codex.models:
+    print(f"  {model.name}: {model.description}")
+```
+
+The catalog covers all four providers — each with model names, reasoning
+levels, default settings, and visibility flags.
+
+Model lists are resolved with a three-tier fallback:
+
+1. **User override** — drop a JSON file at
+   `~/.config/coding-cli-runtime/providers/<provider>.json` to use your own
+   model list immediately, without waiting for a package update.
+2. **Live CLI cache** — for Codex, the library reads
+   `~/.codex/models_cache.json` (auto-refreshed by the Codex CLI) when
+   present. Other providers fall through because their CLIs don't expose a
+   machine-readable model list.
+3. **Hardcoded fallback** — the model list shipped with the package.
+
+Override file format:
+
+```json
+{
+  "default_model": "claude-sonnet-4-7",
+  "models": [
+    "claude-sonnet-4-7",
+    {
+      "name": "claude-opus-5",
+      "description": "Latest opus model",
+      "controls": [
+        { "name": "effort", "kind": "choice", "choices": ["low", "high"], "default": "low" }
+      ]
+    }
+  ]
+}
+```
+
+Set `CODING_CLI_RUNTIME_CONFIG_DIR` to change the config directory
+(default: `~/.config/coding-cli-runtime`).
+
+### Decide whether to retry a failed run
+
+```python
+from coding_cli_runtime import classify_provider_failure
+
+classification = classify_provider_failure(
+    provider="gemini",
+    stderr_text="429 Resource exhausted: rate limit exceeded",
+)
+
+if classification.retryable:
+    print(f"Retryable ({classification.category}) — will retry")
+else:
+    print(f"Fatal ({classification.category}) — giving up")
+```
+
+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
+from coding_cli_runtime import get_provider_contract, build_env_overlay, resolve_config_paths, render_prompt
+
+# Get structured metadata for any supported provider
+contract = get_provider_contract("claude")
+print(contract.binary)                        # "claude"
+print(contract.auth.api_key_env_var)          # "CLAUDE_API_KEY"
+print(contract.paths.config_dir)              # "~/.claude"
+print(contract.headless.approval.flag)        # "--dangerously-skip-permissions"
+
+# Build env var overlay for subprocess
+env = build_env_overlay(contract, api_key="sk-...", base_url="https://custom.example.com")
+# {"CLAUDE_API_KEY": "sk-...", "ANTHROPIC_BASE_URL": "https://custom.example.com"}
+
+# Resolve config paths for container mounts
+host_dir, container_dir = resolve_config_paths(contract, containerized=True)
+# ("/home/user/.claude", "/root/.claude")
+
+# Resolve prompt delivery (stdin vs flag vs activation)
+payload = render_prompt(contract.headless.prompt, "Fix the bug")
+# payload.args = ()            (stdin delivery for Claude)
+# payload.stdin_text = "Fix the bug"
+```
+
+`ProviderContract` is structured as nested sub-contracts
+(`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 — 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 |
+|------|---------|
+| `CliRunRequest` | Command spec: cmd, cwd, env, timeout, stream paths |
+| `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, 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
+
+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
+
+This package does **not** bundle any CLI binaries or credentials. You must
+install and authenticate the relevant provider CLI yourself before using the
+execution helpers.
+
+## Status
+
+Pre-1.0. API may change between minor versions.
+
+## License
+
+MIT

{coding_cli_runtime-0.2.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.2.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.2.0"
+current_version = "0.4.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true