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

coding_cli_runtime-0.3.0/CHANGELOG.md

@@ -0,0 +1,101 @@
+# 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.

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

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

coding_cli_runtime-0.3.0/README.md

@@ -0,0 +1,261 @@
+# 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.
+
+### 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`) so consumers
+can drill into whichever aspect they need. This is reference metadata,
+not a command-construction control plane — consumers keep their own
+command assembly and adopt contract fields selectively.
+
+### Build headless launch commands
+
+```python
+from coding_cli_runtime import build_claude_headless_core, build_codex_headless_core
+
+# Claude: binary + --print + --permission-mode + --dangerously-skip-permissions + --model
+cmd = build_claude_headless_core("claude-sonnet-4-6")
+cmd.extend(["--output-format", "text", "--disallowedTools", "Bash,Task"])
+
+# Codex: binary + exec + --full-auto + --sandbox + --skip-git-repo-check + --model
+cmd = build_codex_headless_core("gpt-5.4", sandbox_mode="read-only")
+cmd.extend(["-C", str(workdir)])
+```
+
+Headless core helpers emit the standard flags for non-interactive runs.
+Consumers append app-specific tails (tool restrictions, output paths, etc.).
+
+### Find session logs after a run
+
+```python
+import time
+from coding_cli_runtime import find_codex_session, find_claude_session
+
+# Find the most recent Codex session log for a given working directory
+session = find_codex_session("/path/to/project", since_ts=time.time() - 300)
+if session:
+    print(f"Session log: {session}")  # ~/.codex/sessions/.../conversation.jsonl
+```
+
+Works for Codex and Claude. Scans provider config directories for session
+files matching the working directory and time window.
+
+## Key types
+
+| Type | Purpose |
+|------|---------|
+| `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 launch) |
+| `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.
+Observability labels (`job_name`, `phase_tag`) default to sensible values.
+
+## API summary
+
+The full public API is listed in [`__init__.py`](src/coding_cli_runtime/__init__.py).
+Key function groups:
+
+| Group | Functions |
+|-------|-----------|
+| Execution | `run_cli_command`, `run_cli_command_sync`, `run_interactive_session` |
+| Provider metadata | `get_provider_contract`, `get_provider_spec`, `list_provider_specs` |
+| Contract helpers | `build_env_overlay`, `resolve_config_paths`, `render_prompt`, `resolve_auth` |
+| Headless launch | `build_claude_headless_core`, `build_codex_headless_core`, `build_copilot_headless_core`, `build_gemini_headless_core` |
+| Codex batch | `build_codex_exec_spec` |
+| Failure handling | `classify_provider_failure` |
+| Session logs | `find_codex_session`, `find_claude_session` |
+| Schema | `load_schema`, `validate_payload` |
+| Utilities | `redact_text`, `build_model_id`, `normalize_path_str` |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and quality checks.
+
+## Prerequisites
+
+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.1.0 → coding_cli_runtime-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coding-cli-runtime"
-version = "0.1.0"
+version = "0.3.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.1.0"
+current_version = "0.3.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 commit = true

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

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 from .auth import AuthResolution, resolve_auth
 from .codex_cli import CodexExecSpec, build_codex_exec_spec
@@ -15,6 +15,26 @@ 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,
+    HeadlessContract,
+    PathContract,
+    PromptPayload,
+    PromptTransport,
+    ProviderContract,
+    SandboxContract,
+    build_env_overlay,
+    get_provider_contract,
+    render_prompt,
+    resolve_config_paths,
+)
 from .provider_controls import build_model_id, resolve_provider_model_controls
 from .provider_specs import (
     ChoiceSpec,
@@ -56,6 +76,8 @@ from .session_logs import (
 from .subprocess_runner import run_cli_command, run_cli_command_sync
 
 __all__ = [
+    "ApprovalContract",
+    "AuthContract",
     "AuthMode",
     "AuthResolution",
     "CliRunRequest",
@@ -67,14 +89,26 @@ __all__ = [
     "ControlSpec",
     "ErrorCode",
     "FailureClassification",
+    "HeadlessContract",
     "ModelSpec",
+    "PathContract",
+    "PromptPayload",
+    "PromptTransport",
+    "ProviderContract",
     "ProviderSpec",
+    "SandboxContract",
     "SchemaValidationError",
     "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",
@@ -85,14 +119,16 @@ __all__ = [
     "get_copilot_model_catalog",
     "get_gemini_default_model",
     "get_gemini_model_options",
+    "get_provider_contract",
     "get_provider_spec",
     "list_provider_specs",
     "build_model_id",
-    "build_codex_exec_spec",
     "classify_provider_failure",
     "load_schema",
+    "render_prompt",
     "resolve_auth",
     "resolve_claude_reasoning_policy",
+    "resolve_config_paths",
     "resolve_provider_model_controls",
     "redact_text",
     "claude_project_key",