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

coding_cli_runtime/__init__.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.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/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.dist-info → coding_cli_runtime-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-cli-runtime
-Version: 0.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.dist-info → coding_cli_runtime-0.4.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-coding_cli_runtime/__init__.py,sha256=S_dSga-xYos95nGC4yq8gQ2SvAUrpERnAFyJ-_SZDkY,3845
+coding_cli_runtime/__init__.py,sha256=06_cwfOA9AMqD6oj5H7_uGj1405leIL6eYc_vCFOREg,4321
 coding_cli_runtime/auth.py,sha256=XP3TZINazvzKcrdgp-pcJcbG4s220dbVVPjF7ivI-wA,2284
 coding_cli_runtime/codex_cli.py,sha256=h26tfb1Kj9LyQV19OvMV-DS4NKvdWrDPXVKGhS8lALI,3002
 coding_cli_runtime/contracts.py,sha256=teYMPDYCjL6HRwRBucJKetfZKlRnxpG82BrC1Y1OMNg,1764
@@ -7,7 +7,7 @@ coding_cli_runtime/copilot_reasoning_logs.py,sha256=S2GD0zGgwVXAPe-DyJPKMR5j-EgO
 coding_cli_runtime/failure_classification.py,sha256=fjGOjtQaBh6Y13gEIS7ystmadcrFKsLAN-fccBuerBs,6027
 coding_cli_runtime/headless.py,sha256=0q0L-crpIRb4A7GCOH2kyoSnyw37USGyFTzP6OOQq9Q,4186
 coding_cli_runtime/json_io.py,sha256=1RseVXV-uPWRm_-pGIUTAvhALnMAEivCX46zvlVpri0,2665
-coding_cli_runtime/provider_contracts.py,sha256=IgwpuF5_imwdVARzb2azKsitutahlUTN_KWZxn3Kvw0,15422
+coding_cli_runtime/provider_contracts.py,sha256=-UhDva-gAWLTgk1ZFxo2gKNpb5GL6Cba68yJR9YB47w,20630
 coding_cli_runtime/provider_controls.py,sha256=2rl1XxGYFODu6LRx3bLhptgN5M_T3klx2lqT_gAAkb0,3328
 coding_cli_runtime/provider_specs.py,sha256=n9cptkPVI5sIBVuJlqE8nuTU7SyJwG8rkUF2enM_KZc,26777
 coding_cli_runtime/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
@@ -19,8 +19,8 @@ coding_cli_runtime/session_logs.py,sha256=wyHld9yVydWd06jSxFSW7MwzxSbiJVLNzKN4Hh
 coding_cli_runtime/subprocess_runner.py,sha256=WqYMI6ALWFhEUySycfHXEtXuCX3m5x7s1n3Bd0TyPm0,11419
 coding_cli_runtime/schemas/normalized_run_result.v1.json,sha256=ogVKJbDFAd9dJklmp8SUkdR9L5EX1rdHGj5leJJHXGs,1110
 coding_cli_runtime/schemas/reasoning_metadata.v1.json,sha256=nQWhqp9-dlzJM18OARDUwAyaA-3-I8rETZYvkgTAnOc,467
-coding_cli_runtime-0.3.0.dist-info/licenses/LICENSE,sha256=hVIuaMVAgQkhTh44et0cpDtN3kGOZnKQ2bY1rJJw-MI,1078
-coding_cli_runtime-0.3.0.dist-info/METADATA,sha256=e9518dIGTaGLay8wou9xEF2V1tjsqqPsZghRLSjIvKs,10801
-coding_cli_runtime-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-coding_cli_runtime-0.3.0.dist-info/top_level.txt,sha256=-tzjii3Qf_GTevxT5M46tITBY02R-K8Ew04hJRHOB2Y,19
-coding_cli_runtime-0.3.0.dist-info/RECORD,,
+coding_cli_runtime-0.4.0.dist-info/licenses/LICENSE,sha256=hVIuaMVAgQkhTh44et0cpDtN3kGOZnKQ2bY1rJJw-MI,1078
+coding_cli_runtime-0.4.0.dist-info/METADATA,sha256=wh9K2YDO1-741eS4nRnSwDY4t0LBpLh9eOb9QtgMzgE,13099
+coding_cli_runtime-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+coding_cli_runtime-0.4.0.dist-info/top_level.txt,sha256=-tzjii3Qf_GTevxT5M46tITBY02R-K8Ew04hJRHOB2Y,19
+coding_cli_runtime-0.4.0.dist-info/RECORD,,