coding-cli-runtime 0.1.0__py3-none-any.whl

coding_cli_runtime/py.typed

@@ -0,0 +1 @@
+

coding_cli_runtime/reasoning.py

@@ -0,0 +1,95 @@
+"""Reasoning control policy helpers shared across Claude callers."""
+
+from __future__ import annotations
+
+from .contracts import ClaudeReasoningPolicy
+
+CLAUDE_ADAPTIVE_THINKING_MODELS: tuple[str, ...] = ("claude-sonnet-4-6", "claude-opus-4-6")
+CLAUDE_EFFORT_CHOICES: tuple[str, ...] = ("low", "medium", "high")
+CLAUDE_DEFAULT_THINKING_TOKENS = 8192
+
+
+def _normalize_claude_effort(value: str | None) -> str | None:
+    if not isinstance(value, str):
+        return None
+    normalized = value.strip().lower()
+    if normalized in CLAUDE_EFFORT_CHOICES:
+        return normalized
+    return None
+
+
+def _uses_claude_adaptive_thinking_model(model: str | None) -> bool:
+    normalized = (model or "").strip().lower()
+    if not normalized:
+        return False
+    return any(normalized.startswith(prefix) for prefix in CLAUDE_ADAPTIVE_THINKING_MODELS)
+
+
+def resolve_claude_reasoning_policy(
+    *,
+    model: str | None,
+    thinking_tokens: int | None,
+    effort: str | None,
+) -> ClaudeReasoningPolicy:
+    normalized_tokens: int | None = None
+    if isinstance(thinking_tokens, int):
+        normalized_tokens = max(int(thinking_tokens), 0)
+    normalized_effort = _normalize_claude_effort(effort)
+    adaptive_model = _uses_claude_adaptive_thinking_model(model)
+
+    if adaptive_model:
+        if normalized_effort:
+            # --effort explicitly set: use it, ignore thinking tokens.
+            return ClaudeReasoningPolicy(
+                mode="effort",
+                effective_effort=normalized_effort,
+                effort_source="flag",
+                thinking_tokens=None,
+            )
+        if normalized_tokens is None:
+            # Neither --effort nor --thinking-tokens: let Claude Code
+            # handle its own defaults.
+            return ClaudeReasoningPolicy(
+                mode="none",
+                effective_effort=None,
+                effort_source=None,
+                thinking_tokens=None,
+            )
+        if normalized_tokens <= 0:
+            return ClaudeReasoningPolicy(
+                mode="disabled",
+                effective_effort=None,
+                effort_source="thinking_tokens<=0",
+                thinking_tokens=0,
+                disable_via_env_setting=True,
+            )
+        # --thinking-tokens passed without --effort: respect the explicit
+        # token budget and pass it through to the CLI as-is.
+        return ClaudeReasoningPolicy(
+            mode="legacy_tokens",
+            effective_effort=None,
+            effort_source=None,
+            thinking_tokens=normalized_tokens,
+        )
+
+    if normalized_tokens is None:
+        return ClaudeReasoningPolicy(
+            mode="none",
+            effective_effort=None,
+            effort_source=None,
+            thinking_tokens=None,
+        )
+    if normalized_tokens > 0:
+        return ClaudeReasoningPolicy(
+            mode="legacy_tokens",
+            effective_effort=None,
+            effort_source=None,
+            thinking_tokens=normalized_tokens,
+        )
+    return ClaudeReasoningPolicy(
+        mode="disabled",
+        effective_effort=None,
+        effort_source="thinking_tokens<=0",
+        thinking_tokens=0,
+        disable_via_env_setting=False,
+    )

coding_cli_runtime/redaction.py

@@ -0,0 +1,20 @@
+"""Log redaction helpers for shared runtime diagnostics."""
+
+from __future__ import annotations
+
+import re
+
+SENSITIVE_PATTERNS = (
+    re.compile(r"(api[_-]?key\s*[=:]\s*)([^\s\"']+)", re.IGNORECASE),
+    re.compile(r"(authorization\s*[:=]\s*bearer\s+)([^\s\"']+)", re.IGNORECASE),
+    re.compile(r"(token\s*[=:]\s*)([^\s\"']+)", re.IGNORECASE),
+)
+
+
+def redact_text(text: str) -> str:
+    if not text:
+        return text
+    redacted = text
+    for pattern in SENSITIVE_PATTERNS:
+        redacted = pattern.sub(r"\1<redacted>", redacted)
+    return redacted

coding_cli_runtime/schema_validation.py

@@ -0,0 +1,101 @@
+"""Minimal JSON-schema-like validation for shared runtime contracts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .json_io import load_packaged_json_object, packaged_resource_exists
+
+
+class SchemaValidationError(ValueError):
+    """Raised when payload validation against shared schema fails."""
+
+
+def _schema_resource_name(schema_name: str) -> str:
+    if not schema_name.endswith(".json"):
+        schema_name = f"{schema_name}.json"
+    return schema_name
+
+
+def load_schema(schema_name: str) -> dict[str, Any]:
+    resource_name = _schema_resource_name(schema_name)
+    if not packaged_resource_exists("schemas", resource_name):
+        raise FileNotFoundError(f"schema not found: schemas/{resource_name}")
+    return load_packaged_json_object("schemas", resource_name)
+
+
+def _python_type_matches(value: Any, expected_type: str) -> bool:
+    if expected_type == "string":
+        return isinstance(value, str)
+    if expected_type == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected_type == "number":
+        return (isinstance(value, int) or isinstance(value, float)) and not isinstance(value, bool)
+    if expected_type == "object":
+        return isinstance(value, dict)
+    if expected_type == "null":
+        return value is None
+    if expected_type == "array":
+        return isinstance(value, list)
+    if expected_type == "boolean":
+        return isinstance(value, bool)
+    return True
+
+
+def _allowed_types(prop_schema: dict[str, Any]) -> list[str]:
+    type_field = prop_schema.get("type")
+    if isinstance(type_field, str):
+        return [type_field]
+    if isinstance(type_field, list):
+        return [item for item in type_field if isinstance(item, str)]
+    return []
+
+
+def validate_payload(payload: Any, schema_name: str) -> None:
+    schema = load_schema(schema_name)
+    if not isinstance(payload, dict):
+        raise SchemaValidationError("payload must be an object")
+
+    required = schema.get("required") or []
+    for key in required:
+        if key not in payload:
+            raise SchemaValidationError(f"missing required field: {key}")
+
+    properties = schema.get("properties")
+    if not isinstance(properties, dict):
+        return
+
+    for key, prop_schema in properties.items():
+        if key not in payload:
+            continue
+        if not isinstance(prop_schema, dict):
+            continue
+        value = payload[key]
+        allowed_types = _allowed_types(prop_schema)
+        if allowed_types and not any(_python_type_matches(value, t) for t in allowed_types):
+            raise SchemaValidationError(
+                f"invalid type for field '{key}': "
+                f"expected {allowed_types}, got {type(value).__name__}"
+            )
+
+        nested_required = prop_schema.get("required") or []
+        if isinstance(value, dict) and isinstance(nested_required, list):
+            for nested_key in nested_required:
+                if nested_key not in value:
+                    raise SchemaValidationError(f"missing required field: {key}.{nested_key}")
+
+            nested_props = prop_schema.get("properties")
+            if isinstance(nested_props, dict):
+                for nested_key, nested_schema in nested_props.items():
+                    if nested_key not in value or not isinstance(nested_schema, dict):
+                        continue
+                    nested_value = value[nested_key]
+                    nested_types = _allowed_types(nested_schema)
+                    if nested_types and not any(
+                        _python_type_matches(nested_value, t) for t in nested_types
+                    ):
+                        raise SchemaValidationError(
+                            "invalid type for field "
+                            f"'{key}.{nested_key}': expected {nested_types}, "
+                            f"got {type(nested_value).__name__}"
+                        )

coding_cli_runtime/schemas/normalized_run_result.v1.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "NormalizedCliRunResultV1",
+  "type": "object",
+  "required": [
+    "provider",
+    "model",
+    "run_id",
+    "status",
+    "error_code",
+    "duration_seconds"
+  ],
+  "properties": {
+    "provider": {"type": "string"},
+    "model": {"type": "string"},
+    "run_id": {"type": "string"},
+    "status": {"type": "string"},
+    "error_code": {"type": "string"},
+    "error_message": {"type": ["string", "null"]},
+    "duration_seconds": {"type": "number"},
+    "stdout_path": {"type": ["string", "null"]},
+    "stderr_path": {"type": ["string", "null"]},
+    "session_path": {"type": ["string", "null"]},
+    "created_at": {"type": ["string", "null"]},
+    "reasoning": {
+      "type": ["object", "null"],
+      "required": ["mode", "effort", "thinking_budget_tokens"],
+      "properties": {
+        "mode": {"type": ["string", "null"]},
+        "effort": {"type": ["string", "null"]},
+        "thinking_budget_tokens": {"type": ["integer", "null"]}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

coding_cli_runtime/schemas/reasoning_metadata.v1.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ReasoningMetadataV1",
+  "type": "object",
+  "required": ["mode", "effort", "thinking_budget_tokens"],
+  "properties": {
+    "mode": {"type": ["string", "null"]},
+    "effort": {"type": ["string", "null"]},
+    "thinking_budget_tokens": {"type": ["integer", "null"]},
+    "source": {"type": ["string", "null"]},
+    "schema": {"type": ["string", "null"]}
+  },
+  "additionalProperties": true
+}