devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/llm/invoke.py

@@ -0,0 +1,1322 @@
+from __future__ import annotations
+
+import json
+import re
+import shlex
+import tempfile
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from ..devflow_state import _postgrest_request, _resolve_supabase_rest_config
+from ..idea.traditional_stories import _global_devflow_dir, _read_toml
+from .cli_one_shot import run_one_shot
+from .cli_stream import run_streaming
+from .provider_api import (
+    ANTHROPIC_MODEL_DEFAULT,
+    GOOGLE_MODEL_DEFAULT,
+    OLLAMA_MODEL_DEFAULT,
+    OPENAI_MODEL_DEFAULT,
+    anthropic_messages_create,
+    anthropic_response_text,
+    canonical_provider_api_shape,
+    google_generate_content,
+    google_response_text,
+    load_anthropic_api_settings,
+    load_google_api_settings,
+    load_openai_api_settings,
+    openai_response_text,
+    openai_responses_create,
+)
+
+DeliveryModel = Literal["final_only", "streaming"]
+InteractionModel = Literal["request_response", "agentic"]
+LlmTransport = Literal["cli", "api"]
+ResponseContract = Literal["text", "json_only"]
+
+_SUPPORTED_DELIVERY_MODELS = {"final_only", "streaming"}
+_SUPPORTED_INTERACTION_MODELS = {"request_response", "agentic"}
+_SUPPORTED_DELIVERIES = {"argument", "stdin"}
+_SUPPORTED_RESPONSE_CONTRACTS = {"text", "json_only"}
+_SUPPORTED_STRENGTHS = {"ultra_light", "light", "medium", "strong"}
+_STRENGTH_SHORTHAND = {"xs": "ultra_light", "s": "strong", "m": "medium", "l": "light", "ul": "ultra_light"}
+
+
+def _normalize_strength(value: str | None) -> str | None:
+    """Normalize a strength shorthand (M, L, S, XS) to its canonical name."""
+    if value is None:
+        return None
+    v = str(value).strip().lower()
+    return _STRENGTH_SHORTHAND.get(v, v)
+_SUPPORTED_TRANSPORTS = {"cli", "api"}
+_SUPPORTED_PROVIDER_FAMILIES = {"anthropic", "openai", "google", "minimax", "ollama"}
+_PROVIDER_ALIASES = {
+    "anthropic": "anthropic",
+    "claude": "anthropic",
+    "openai": "openai",
+    "codex": "openai",
+    "google": "google",
+    "gemini": "google",
+    "gemini-cli": "google",
+    "pi": "minimax",
+    "minimax": "minimax",
+    "ollama": "ollama",
+}
+_INTERACTION_MODEL_ALIASES = {
+    "request_response": "request_response",
+    "request/response": "request_response",
+    "agentic": "agentic",
+    "delegated": "agentic",
+}
+_API_TIER_ALIASES = {
+    "ultra_light": "ultra_light",
+    "ultra-light": "ultra_light",
+    "ultralight": "ultra_light",
+    "light": "light",
+    "medium": "medium",
+    "mid": "medium",
+    "strong": "strong",
+}
+_AUTOLOADING_CLI_PROVIDERS = {"anthropic"}
+_AUTOLOADING_CLI_BINARIES = {"claude", "codex"}
+_PROMPT_INLINE_BYTES_LIMIT = 120_000
+_PROMPT_SECTION_INLINE_BYTES_LIMIT = 48_000
+_PROMPT_ARTIFACT_DIRNAME = "llm_prompt_artifacts"
+_PROMPT_ARTIFACT_MAX_FILENAME_LENGTH = 48
+
+
+def _load_global_llm_cfg() -> dict[str, Any]:
+    raw = _read_toml(_global_devflow_dir() / "config.toml")
+    # _read_toml may return {} on parse failure but the raw file may still contain
+    # tiers as a Python dict-string (ast.literal_eval-able).  Wire it through
+    # _parse_tiers so the tiers key is available even when tomllib can't parse it.
+    if "tiers" not in raw:
+        raw = dict(raw)
+        raw["tiers"] = _parse_tiers(raw)
+    return raw
+
+
+def _nested_dict(mapping: dict[str, Any], *path: str) -> dict[str, Any] | None:
+    current: Any = mapping
+    for key in path:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(key)
+    return current if isinstance(current, dict) else None
+
+
+def _parse_tiers(cfg: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Parse the tiers dict from global config, handling both TOML native and
+    JSON-string formats (e.g. tiers stored as a Python literal string)."""
+    raw = cfg.get("tiers")
+    if isinstance(raw, dict):
+        return raw
+    if isinstance(raw, str):
+        raw = raw.strip()
+        if not raw:
+            return {}
+        # Try TOML inline table first.
+        try:
+            import tomllib
+            # Re-parse the full config as TOML to get inline table parsed.
+            # Fast path: if it looks like Python literal, use ast.literal_eval.
+            if raw.startswith("{") or raw.startswith("'"):
+                import ast
+                try:
+                    parsed = ast.literal_eval(raw)
+                    if isinstance(parsed, dict):
+                        return parsed
+                except Exception:
+                    pass
+        except Exception:
+            pass
+    return {}
+
+
+def _tier_config(strength: str, cfg: dict[str, Any]) -> dict[str, Any] | None:
+    """Return the tier config for the given strength, or None if not configured."""
+    tiers = _parse_tiers(cfg)
+    tier = tiers.get(strength)
+    if isinstance(tier, dict):
+        return tier
+    return None
+
+
+def _canonical_light_tier_from_supabase() -> dict[str, Any]:
+    """Return the canonical ``devflow_settings.settings.tiers.light`` payload.
+
+    This is the source-of-truth path for the user-selected DevFlow light tier.
+    We query Supabase first so Devin 2.0 / PI-adjacent flows do not drift to
+    repo-local or other legacy local config surfaces.
+    """
+    config = _resolve_supabase_rest_config()
+    if config is None:
+        return {}
+    url, key = config
+    try:
+        rows = _postgrest_request(
+            method="GET",
+            url=f"{url}/rest/v1/devflow_settings?select=settings&order=updated_at.desc.nullslast&limit=1",
+            key=key,
+        )
+    except Exception:
+        return {}
+    if not isinstance(rows, list) or not rows or not isinstance(rows[0], dict):
+        return {}
+    settings = (rows[0] or {}).get("settings")
+    if not isinstance(settings, dict):
+        return {}
+    return _nested_dict(settings, "tiers", "light") or {}
+
+
+def _canonical_light_tier_from_global_cfg(cfg: dict[str, Any]) -> dict[str, Any]:
+    for path in (
+        ("devflow_settings", "settings", "tiers", "light"),
+        ("settings", "tiers", "light"),
+        ("tiers", "light"),
+    ):
+        candidate = _nested_dict(cfg, *path)
+        if candidate is not None:
+            return candidate
+    return {}
+
+
+def _canonical_light_tier_payload(cfg: dict[str, Any] | None = None) -> dict[str, Any]:
+    payload = _canonical_light_tier_from_supabase()
+    if payload:
+        return payload
+    resolved_cfg = cfg if cfg is not None else _load_global_llm_cfg()
+    return _canonical_light_tier_from_global_cfg(resolved_cfg)
+
+
+def _canonical_light_tier_provider(payload: dict[str, Any]) -> str | None:
+    return _normalize_provider_name(
+        str(
+            payload.get("apiProvider")
+            or payload.get("api_provider")
+            or payload.get("llm_provider")
+            or payload.get("provider")
+            or ""
+        ).strip()
+    )
+
+
+def _canonical_light_tier_model(payload: dict[str, Any]) -> str | None:
+    model = str(
+        payload.get("apiModel")
+        or payload.get("api_model")
+        or payload.get("llm_model")
+        or payload.get("model")
+        or payload.get("model_default")
+        or ""
+    ).strip()
+    return model or None
+
+
+def resolve_canonical_light_tier_model(*, cfg: dict[str, Any] | None = None) -> str | None:
+    """Return the canonical light-tier model for Devin 2.0 / PI launch paths.
+
+    Prefers the direct Supabase ``devflow_settings.settings.tiers.light`` row,
+    then falls back to the synced global DevFlow config view when Supabase is
+    unavailable. This intentionally avoids repo-local / legacy local config.
+    """
+    payload = _canonical_light_tier_payload(cfg)
+    model = _canonical_light_tier_model(payload)
+    if model:
+        return model
+    resolved_cfg = cfg if cfg is not None else _load_global_llm_cfg()
+    fallback = str(resolved_cfg.get("llm_cli_model_weak") or resolved_cfg.get("llm_cli_model_default") or "").strip()
+    return fallback or None
+
+
+def _normalize_api_tier(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
+    if not normalized:
+        return None
+    return _API_TIER_ALIASES.get(normalized)
+
+
+def resolve_api_tier_request_overrides(
+    *,
+    tier: str,
+    cfg: dict[str, Any] | None = None,
+    strength_override: str | None = None,
+) -> dict[str, Any]:
+    """Resolve API-call overrides for the canonical DevFlow tier ladder.
+
+    Important Devin/PI harness note: the light-tier source of truth is the
+    user-managed DevFlow settings row in Supabase
+    (``devflow_settings.settings.tiers.light``). This helper prefers that
+    canonical row directly, then falls back to the synced global DevFlow
+    config view only when Supabase is unavailable, and never consults repo-
+    local or other legacy local config.
+
+    ``tier='light'`` means "use the canonical DevFlow light tier."
+    ``tier='medium'`` means "use the tier medium override if configured."
+    ``tier='strong'`` means "use the tier strong override if configured."
+    ``tier='ultra_light'`` means "use the ultra_light tier."
+    """
+    normalized_tier = _normalize_api_tier(tier)
+    if normalized_tier not in {"ultra_light", "light", "medium", "strong"}:
+        raise RuntimeError(f"Unsupported API tier: {tier!r}")
+    resolved_cfg = cfg if cfg is not None else _load_global_llm_cfg()
+    overrides: dict[str, Any] = {
+        "transport": "api",
+    }
+    if normalized_tier == "light":
+        # Light is always sourced from Supabase as canonical.
+        light_payload = _canonical_light_tier_payload(resolved_cfg)
+        provider = _canonical_light_tier_provider(light_payload)
+        model = _canonical_light_tier_model(light_payload)
+        if provider:
+            overrides["provider"] = provider
+        if model:
+            overrides["model"] = model
+        return overrides
+    if normalized_tier == "medium":
+        overrides["strength"] = strength_override or "strong"
+        return overrides
+    if normalized_tier == "strong":
+        tier_cfg = _tier_config("strong", resolved_cfg)
+        if tier_cfg:
+            provider = _normalize_provider_name(
+                str(tier_cfg.get("apiProvider") or tier_cfg.get("provider") or "").strip()
+            )
+            model = str(tier_cfg.get("apiModel") or tier_cfg.get("model") or "").strip() or None
+            if provider:
+                overrides["provider"] = provider
+            if model:
+                overrides["model"] = model
+            return overrides
+        overrides["strength"] = strength_override or "strong"
+        return overrides
+
+    # ultra_light
+    tier_cfg = _tier_config("ultra_light", resolved_cfg)
+    if tier_cfg:
+        provider = _normalize_provider_name(
+            str(tier_cfg.get("apiProvider") or tier_cfg.get("provider") or "").strip()
+        )
+        model = str(tier_cfg.get("apiModel") or tier_cfg.get("model") or "").strip() or None
+        if provider:
+            overrides["provider"] = provider
+        if model:
+            overrides["model"] = model
+        return overrides
+    overrides["strength"] = strength_override or "ultra_light"
+    return overrides
+
+
+def normalize_llm_cli_base(base_cmd: str) -> str:
+    """Normalise a CLI base command and add required provider flags."""
+    parts = shlex.split(base_cmd)
+    if not parts:
+        raise RuntimeError("LLM CLI base command not set.")
+    if parts[0] == "ollama" and (len(parts) == 1 or parts[1] != "run"):
+        parts.insert(1, "run")
+    if parts[0] == "claude" and "--dangerously-skip-permissions" not in parts:
+        parts.append("--dangerously-skip-permissions")
+    if parts[:2] == ["codex", "exec"] and "--dangerously-bypass-approvals-and-sandbox" not in parts:
+        parts.append("--dangerously-bypass-approvals-and-sandbox")
+    if parts[0] == "pi" and "-p" not in parts and "--print" not in parts:
+        parts.append("-p")
+    return " ".join(parts)
+
+
+def _apply_model_flag(base_cmd: str, model: str | None) -> str:
+    """Append --model <model> to a CLI base command (provider-aware).
+
+    - ollama: appends model as positional arg after ``run`` (ollama run <model>)
+    - codex / claude / minimax / pi / other: appends ``--model <model>``
+    - If model is None or already present as a --model flag, returns base_cmd unchanged.
+    """
+    if not model:
+        return base_cmd
+    parts = shlex.split(base_cmd)
+    if not parts:
+        return base_cmd
+    # Don't double-apply
+    if "--model" in parts:
+        return base_cmd
+    provider = _normalize_provider_name(parts[0])
+    if provider == "ollama":
+        # ollama run <model> — model is a positional arg after the subcommand
+        return f"{base_cmd} {model}"
+    return f"{base_cmd} --model {model}"
+
+
+def _extract_model_flag(base_cmd: str) -> str | None:
+    """Pull the model value from a base_cmd that may contain --model <value>."""
+    parts = shlex.split(base_cmd)
+    for i, part in enumerate(parts):
+        if part == "--model" and i + 1 < len(parts):
+            return parts[i + 1]
+    return None
+
+
+def _normalize_provider_name(provider: str | None) -> str | None:
+    if provider is None:
+        return None
+    raw = str(provider).strip()
+    if not raw:
+        return None
+    normalized = raw.lower()
+    basename = raw.replace("\\", "/").rsplit("/", 1)[-1].strip().lower()
+    for candidate in (normalized, basename):
+        if not candidate:
+            continue
+        aliased = _PROVIDER_ALIASES.get(candidate, candidate)
+        if candidate in _PROVIDER_ALIASES or aliased in _SUPPORTED_PROVIDER_FAMILIES:
+            return aliased
+    return _PROVIDER_ALIASES.get(normalized, normalized)
+
+
+def _normalize_interaction_model(value: str | None) -> InteractionModel | None:
+    if value is None:
+        return None
+    normalized = str(value).strip().lower()
+    if not normalized:
+        return None
+    return _INTERACTION_MODEL_ALIASES.get(normalized)  # type: ignore[return-value]
+
+
+def _infer_provider_from_base_cmd(base_cmd: str) -> str | None:
+    parts = shlex.split(base_cmd)
+    if not parts:
+        return None
+    return _normalize_provider_name(parts[0])
+
+
+def _cli_binary_name(base_cmd: str) -> str | None:
+    parts = shlex.split(base_cmd)
+    if not parts:
+        return None
+    binary = Path(parts[0]).name.strip().lower()
+    return binary or None
+
+
+def _normalize_string_set(value: Any) -> set[str]:
+    if isinstance(value, str):
+        candidates = [part.strip().lower() for part in value.split(",")]
+        return {candidate for candidate in candidates if candidate}
+    if isinstance(value, (list, tuple, set)):
+        normalized: set[str] = set()
+        for entry in value:
+            text = str(entry).strip().lower()
+            if text:
+                normalized.add(text)
+        return normalized
+    return set()
+
+
+def _autoloading_cli_settings() -> tuple[set[str], set[str]]:
+    cfg = _load_global_llm_cfg()
+    use_defaults = cfg.get("llm_autoloading_cli_use_defaults", True)
+    providers = _normalize_string_set(cfg.get("llm_autoloading_cli_providers"))
+    binaries = _normalize_string_set(cfg.get("llm_autoloading_cli_binaries"))
+    if use_defaults is not False:
+        providers = set(_AUTOLOADING_CLI_PROVIDERS) | providers
+        binaries = set(_AUTOLOADING_CLI_BINARIES) | binaries
+    return providers, binaries
+
+
+def _provider_requires_sanitized_cli_cwd(*, provider: str | None, base_cmd: str) -> bool:
+    normalized_provider = _normalize_provider_name(provider)
+    binary_name = _cli_binary_name(base_cmd)
+    autoloading_providers, autoloading_binaries = _autoloading_cli_settings()
+    return normalized_provider in autoloading_providers or binary_name in autoloading_binaries
+
+
+def _resolve_cli_cwd(*, repo_root: Path, provider: str | None, base_cmd: str) -> Path:
+    if not _provider_requires_sanitized_cli_cwd(provider=provider, base_cmd=base_cmd):
+        return repo_root
+    cli_cwd = Path(tempfile.mkdtemp(prefix="devflow-llm-cwd-"))
+    try:
+        (cli_cwd / "DEVFLOW_REPO_ROOT.txt").write_text(str(repo_root), encoding="utf-8")
+    except OSError:
+        pass
+    return cli_cwd
+
+
+def _prompt_inline_byte_limit(request: "LlmInvocationRequest") -> int:
+    configured = request.artifact_policy.get("prompt_inline_bytes_limit")
+    if configured is None:
+        return _PROMPT_INLINE_BYTES_LIMIT
+    try:
+        parsed = int(configured)
+    except (TypeError, ValueError):
+        return _PROMPT_INLINE_BYTES_LIMIT
+    return parsed if parsed > 0 else _PROMPT_INLINE_BYTES_LIMIT
+
+
+def _prompt_section_inline_byte_limit(request: "LlmInvocationRequest") -> int:
+    configured = request.artifact_policy.get("prompt_section_inline_bytes_limit")
+    if configured is None:
+        return _PROMPT_SECTION_INLINE_BYTES_LIMIT
+    try:
+        parsed = int(configured)
+    except (TypeError, ValueError):
+        return _PROMPT_SECTION_INLINE_BYTES_LIMIT
+    return parsed if parsed > 0 else _PROMPT_SECTION_INLINE_BYTES_LIMIT
+
+
+def _prompt_artifact_root(request: "LlmInvocationRequest") -> Path:
+    configured = request.artifact_policy.get("prompt_artifact_root")
+    if configured:
+        return Path(str(configured)).expanduser()
+    return request.repo_root / ".devflow" / _PROMPT_ARTIFACT_DIRNAME
+
+
+def _prompt_artifact_directory(request: "LlmInvocationRequest") -> Path:
+    root = _prompt_artifact_root(request)
+    root.mkdir(parents=True, exist_ok=True)
+    prefix_base = re.sub(r"[^a-z0-9]+", "-", request.purpose.strip().lower()).strip("-")
+    if not prefix_base:
+        prefix_base = "llm-prompt"
+    prefix = f"{prefix_base[:_PROMPT_ARTIFACT_MAX_FILENAME_LENGTH]}-"
+    return Path(tempfile.mkdtemp(prefix=prefix, dir=root))
+
+
+def _json_byte_size(value: Any) -> int:
+    return len(json.dumps(value, indent=2, sort_keys=True).encode("utf-8"))
+
+
+def _artifact_reference(*, path: Path, key_path: str, value: Any) -> dict[str, Any]:
+    return {
+        "artifact_ref": {
+            "path": str(path),
+            "format": "json",
+            "key_path": key_path,
+            "bytes": _json_byte_size(value),
+        }
+    }
+
+
+def _write_prompt_artifact(*, artifact_dir: Path, key_path: str, value: Any) -> Path:
+    slug_parts = [segment for segment in re.split(r"[^a-zA-Z0-9]+", key_path) if segment]
+    filename = "-".join(slug_parts)[:_PROMPT_ARTIFACT_MAX_FILENAME_LENGTH] or "payload"
+    path = artifact_dir / f"{filename}.json"
+    suffix = 1
+    while path.exists():
+        path = artifact_dir / f"{filename}-{suffix}.json"
+        suffix += 1
+    path.write_text(json.dumps(value, indent=2, sort_keys=True), encoding="utf-8")
+    return path
+
+
+def _compact_prompt_mapping(
+    *,
+    mapping: dict[str, Any],
+    artifact_dir: Path,
+    inline_limit: int,
+    section_limit: int,
+    parent_key_path: str = "",
+) -> tuple[dict[str, Any], int]:
+    compacted: dict[str, Any] = {}
+    artifact_count = 0
+    for key, value in mapping.items():
+        key_path = f"{parent_key_path}.{key}" if parent_key_path else key
+        if isinstance(value, (dict, list, str)) and _json_byte_size(value) > section_limit:
+            artifact_path = _write_prompt_artifact(
+                artifact_dir=artifact_dir,
+                key_path=key_path,
+                value=value,
+            )
+            compacted[key] = _artifact_reference(path=artifact_path, key_path=key_path, value=value)
+            artifact_count += 1
+            continue
+        if isinstance(value, dict):
+            nested, nested_count = _compact_prompt_mapping(
+                mapping=value,
+                artifact_dir=artifact_dir,
+                inline_limit=inline_limit,
+                section_limit=section_limit,
+                parent_key_path=key_path,
+            )
+            if nested_count > 0 and _json_byte_size(nested) <= inline_limit:
+                compacted[key] = nested
+                artifact_count += nested_count
+                continue
+        compacted[key] = value
+    return compacted, artifact_count
+
+
+def _load_cli_config_from_cfg(
+    cfg: dict[str, Any],
+    *,
+    provider_override: str | None = None,
+    model_override: str | None = None,
+) -> tuple[str, str, str]:
+    llm_mode = str(cfg.get("llm_mode") or "").strip().lower()
+    if llm_mode != "cli":
+        raise RuntimeError("LLM not configured for CLI mode.")
+    provider = (
+        _normalize_provider_name(provider_override)
+        or _normalize_provider_name(str(cfg.get("llm_provider") or "").strip())
+        or "cli"
+    )
+    base_cmd = str(cfg.get("llm_cli_base") or "").strip()
+    if not base_cmd:
+        raise RuntimeError("LLM CLI base command not set.")
+    delivery = str(cfg.get("llm_cli_delivery") or "argument").strip().lower()
+    base_cmd = normalize_llm_cli_base(base_cmd)
+    base_cmd = _apply_model_flag(base_cmd, model_override)
+    return provider, base_cmd, delivery
+
+
+def _load_llm_cli_config() -> tuple[str, str]:
+    cfg = _load_global_llm_cfg()
+    _, base_cmd, delivery = _load_cli_config_from_cfg(cfg)
+    return base_cmd, delivery
+
+
+_ANSI_CONTROL_SEQUENCE_RE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+
+def _strip_terminal_control_sequences(raw_text: str) -> str:
+    stripped = _ANSI_CONTROL_SEQUENCE_RE.sub("", raw_text)
+    return "".join(ch if ord(ch) >= 32 else " " for ch in stripped)
+
+
+def _extract_json_payload(raw_text: str) -> Any | None:
+    candidate = _strip_terminal_control_sequences(raw_text).strip()
+    if not candidate:
+        return None
+    if "```" in candidate:
+        for chunk in candidate.split("```"):
+            stripped = chunk.strip()
+            if stripped.startswith("json"):
+                stripped = stripped[4:].strip()
+            if stripped.startswith("{") or stripped.startswith("["):
+                candidate = stripped
+                break
+    decoder = json.JSONDecoder()
+    start_indexes = [0] if candidate[:1] in "[{" else []
+    start_indexes.extend(index for index, char in enumerate(candidate) if char in "[{")
+    seen: set[int] = set()
+    for index in start_indexes:
+        if index in seen:
+            continue
+        seen.add(index)
+        try:
+            parsed, _ = decoder.raw_decode(candidate[index:])
+            return parsed
+        except json.JSONDecodeError:
+            continue
+    return None
+
+
+@dataclass(frozen=True)
+class _PreparedPrompt:
+    text: str
+    original_bytes: int
+    effective_bytes: int
+    was_compacted: bool = False
+    artifact_dir: Path | None = None
+    artifact_count: int = 0
+
+
+def _prepare_request_prompt(request: "LlmInvocationRequest") -> _PreparedPrompt:
+    prompt = request.prompt
+    if prompt:
+        encoded = prompt.encode("utf-8")
+        return _PreparedPrompt(
+            text=prompt,
+            original_bytes=len(encoded),
+            effective_bytes=len(encoded),
+        )
+    if request.prompt_payload is None:
+        raise RuntimeError("LLM invocation prompt is required.")
+
+    prompt_payload = request.prompt_payload
+    original_bytes = _json_byte_size(prompt_payload)
+    inline_limit = _prompt_inline_byte_limit(request)
+    if original_bytes <= inline_limit:
+        rendered = json.dumps(prompt_payload, indent=2, sort_keys=True)
+        return _PreparedPrompt(
+            text=rendered,
+            original_bytes=original_bytes,
+            effective_bytes=len(rendered.encode("utf-8")),
+        )
+
+    artifact_dir = _prompt_artifact_directory(request)
+    compacted_payload, artifact_count = _compact_prompt_mapping(
+        mapping=dict(prompt_payload),
+        artifact_dir=artifact_dir,
+        inline_limit=inline_limit,
+        section_limit=_prompt_section_inline_byte_limit(request),
+    )
+    if artifact_count == 0:
+        payload_artifact = _write_prompt_artifact(
+            artifact_dir=artifact_dir,
+            key_path="prompt_payload",
+            value=prompt_payload,
+        )
+        compacted_payload = {
+            "_devflow_prompt_materialization": {
+                "instructions": (
+                    "The original prompt payload exceeded inline prompt limits. "
+                    "Read the referenced artifact file before completing the task."
+                ),
+                "original_prompt_bytes": original_bytes,
+                "inline_prompt_limit_bytes": inline_limit,
+            },
+            "prompt_payload": _artifact_reference(
+                path=payload_artifact,
+                key_path="prompt_payload",
+                value=prompt_payload,
+            ),
+        }
+        artifact_count = 1
+    else:
+        compacted_payload["_devflow_prompt_materialization"] = {
+            "instructions": (
+                "Large prompt sections were replaced with artifact references. "
+                "Read any referenced files from the workspace before completing the task."
+            ),
+            "original_prompt_bytes": original_bytes,
+            "inline_prompt_limit_bytes": inline_limit,
+        }
+    rendered = json.dumps(compacted_payload, indent=2, sort_keys=True)
+    return _PreparedPrompt(
+        text=rendered,
+        original_bytes=original_bytes,
+        effective_bytes=len(rendered.encode("utf-8")),
+        was_compacted=True,
+        artifact_dir=artifact_dir,
+        artifact_count=artifact_count,
+    )
+
+
+@dataclass(frozen=True)
+class LlmInvocationRequest:
+    purpose: str
+    repo_root: Path
+    prompt: str
+    delivery_model: DeliveryModel | None = None
+    interaction_model: InteractionModel | str | None = None
+    transport: LlmTransport | None = None
+    response_contract: ResponseContract | None = None
+    timeout_seconds: int | None = None
+    strength: str | None = None
+    prompt_payload: dict[str, Any] | None = None
+    event_context: dict[str, Any] = field(default_factory=dict)
+    journal_context: dict[str, Any] = field(default_factory=dict)
+    artifact_policy: dict[str, Any] = field(default_factory=dict)
+    base_cmd: str | None = None
+    delivery: str | None = None
+    provider: str | None = None
+    model: str | None = None
+
+
+@dataclass(frozen=True)
+class LlmInvocationResult:
+    ok: bool
+    status: Literal["ok", "error"]
+    returncode: int
+    stdout: str
+    stderr: str
+    purpose: str
+    repo_root: Path
+    model: str | None
+    transport: LlmTransport = "cli"
+    delivery_model: DeliveryModel = "final_only"
+    interaction_model: InteractionModel = "request_response"
+    provider: str = "cli"
+    base_cmd: str = ""
+    delivery: str = ""
+    response_contract: ResponseContract | None = None
+    parsed_json: Any | None = None
+    contract_ok: bool | None = None
+    contract_error: str | None = None
+    session_id: str | None = None
+    log_path: Path | None = None
+    prompt_characters: int = 0
+    prompt_bytes: int = 0
+    effective_prompt_bytes: int = 0
+    prompt_was_compacted: bool = False
+    prompt_artifact_dir: Path | None = None
+    prompt_artifact_count: int = 0
+    cli_cwd: Path | None = None
+    used_sanitized_cli_cwd: bool = False
+
+
+@dataclass(frozen=True)
+class _ResolvedInvocation:
+    transport: LlmTransport
+    delivery_model: DeliveryModel
+    interaction_model: InteractionModel
+    provider: str
+    base_cmd: str
+    delivery: str
+    model: str | None
+
+
+def _resolve_requested_transport(request: LlmInvocationRequest) -> LlmTransport:
+    if request.transport is not None:
+        return request.transport
+    cfg = _load_global_llm_cfg()
+    # Honour tier config when strength is provided (or default to "medium").
+    strength = _normalize_strength(request.strength) or "medium"
+    tier = _tier_config(strength, cfg)
+    if tier:
+        mode = str(tier.get("mode") or "").strip().lower()
+        llm_mode = str(cfg.get("llm_mode") or "").strip().lower()
+        if (
+            mode == "api"
+            and llm_mode != "api"
+            and any(str(tier.get(key) or "").strip() for key in ("base_cmd", "cliProfile", "cliFamily"))
+        ):
+            return "cli"
+        if mode in ("api", "cli"):
+            return mode
+    return "cli"
+
+
+def _resolve_requested_delivery_model(request: LlmInvocationRequest) -> DeliveryModel:
+    if request.delivery_model is not None:
+        return request.delivery_model
+    return "final_only"
+
+
+def _resolve_requested_interaction_model(request: LlmInvocationRequest) -> InteractionModel:
+    normalized = _normalize_interaction_model(request.interaction_model)
+    if normalized is not None:
+        return normalized
+    return "request_response"
+
+
+
+def _resolve_api_model_from_cfg(
+    cfg: dict[str, Any],
+    *,
+    strength_override: str | None,
+) -> str | None:
+    """Resolve API model from the tier config for the given strength using
+    the TOML tier shape (apiModel for API tiers, cliProfile for CLI)."""
+    strength = strength_override or "medium"
+    tier_cfg = _tier_config(strength, cfg)
+    if tier_cfg:
+        model = str(tier_cfg.get("apiModel") or tier_cfg.get("model") or "").strip()
+        if model:
+            return model
+    # No tier configured — no default for API in this path.
+    return None
+
+
+def _resolve_default_api_model(provider: str | None) -> str | None:
+    normalized_provider = _normalize_provider_name(provider)
+    if normalized_provider == "anthropic":
+        return ANTHROPIC_MODEL_DEFAULT
+    if normalized_provider == "openai":
+        return OPENAI_MODEL_DEFAULT
+    if normalized_provider == "google":
+        return GOOGLE_MODEL_DEFAULT
+    if normalized_provider == "ollama":
+        return OLLAMA_MODEL_DEFAULT
+    return None
+
+
+def _resolve_api_invocation_from_global_cfg(
+    cfg: dict[str, Any],
+    *,
+    request: "LlmInvocationRequest",
+    transport: LlmTransport,
+    delivery_model: DeliveryModel,
+    interaction_model: InteractionModel,
+) -> _ResolvedInvocation | None:
+    llm_mode = str(cfg.get("llm_mode") or "").strip().lower()
+    if llm_mode != "api":
+        return None
+    provider = _normalize_provider_name(request.provider) or _normalize_provider_name(str(cfg.get("llm_provider") or ""))
+    resolved_model = request.model or _resolve_api_model_from_cfg(
+        cfg,
+        strength_override=request.strength,
+    )
+    normalized_strength = _normalize_api_tier(request.strength)
+    if normalized_strength == "light":
+        canonical_light = resolve_api_tier_request_overrides(tier="light", cfg=cfg)
+        provider = (
+            _normalize_provider_name(request.provider)
+            or _normalize_provider_name(str(canonical_light.get("provider") or ""))
+            or provider
+        )
+        resolved_model = request.model or str(canonical_light.get("model") or "").strip() or resolved_model
+    # Only providers that support streaming can use that delivery model via the API path.
+    # Others must use final_only or the request's fallback.
+    if delivery_model == "streaming" and provider not in {"openai", "anthropic", "google"}:
+        delivery_model = "final_only"
+    return _ResolvedInvocation(
+        transport=transport,
+        delivery_model=delivery_model,
+        interaction_model=interaction_model,
+        provider=provider or "provider_api",
+        base_cmd="",
+        delivery="",
+        model=resolved_model,
+    )
+
+
+def _validate_request(request: "LlmInvocationRequest") -> None:
+    if not str(request.purpose).strip():
+        raise RuntimeError("LLM invocation purpose is required.")
+    if not isinstance(request.repo_root, Path):
+        raise RuntimeError("LLM invocation repo_root must be a pathlib.Path.")
+    if request.delivery_model is not None and request.delivery_model not in _SUPPORTED_DELIVERY_MODELS:
+        raise RuntimeError(f"Unsupported LLM delivery_model: {request.delivery_model!r}")
+    normalized_interaction_model = _normalize_interaction_model(request.interaction_model)
+    if request.interaction_model is not None and normalized_interaction_model is None:
+        raise RuntimeError(
+            f"Unsupported LLM interaction_model: {request.interaction_model!r}. "
+            "Supported values: request_response, agentic."
+        )
+    if request.transport is not None and request.transport not in _SUPPORTED_TRANSPORTS:
+        raise RuntimeError(f"Unsupported LLM transport: {request.transport!r}")
+    normalized_provider = _normalize_provider_name(request.provider)
+    if normalized_provider is not None and normalized_provider not in _SUPPORTED_PROVIDER_FAMILIES:
+        raise RuntimeError(
+            f"Unsupported LLM provider: {request.provider!r}. "
+            "Supported explicit providers: anthropic, openai, google, minimax, ollama."
+        )
+    if request.response_contract is not None and request.response_contract not in _SUPPORTED_RESPONSE_CONTRACTS:
+        raise RuntimeError(f"Unsupported LLM response_contract: {request.response_contract!r}")
+    if request.timeout_seconds is not None and request.timeout_seconds <= 0:
+        raise RuntimeError("LLM invocation timeout_seconds must be positive when provided.")
+    if request.strength is not None and _normalize_strength(request.strength) not in _SUPPORTED_STRENGTHS:
+        raise RuntimeError(f"Unsupported LLM strength override: {request.strength!r}")
+    if request.model is not None and not str(request.model).strip():
+        raise RuntimeError("LLM invocation model must be non-empty when provided.")
+    if request.base_cmd is not None or request.delivery is not None:
+        if not request.base_cmd or not request.delivery:
+            raise RuntimeError("Explicit CLI invocation requires both base_cmd and delivery.")
+        if request.delivery not in _SUPPORTED_DELIVERIES:
+            raise RuntimeError(f"Unsupported LLM delivery: {request.delivery!r}")
+    normalized_prompt = request.prompt
+    if not normalized_prompt and request.prompt_payload is not None:
+        normalized_prompt = json.dumps(request.prompt_payload, indent=2, sort_keys=True)
+    if not normalized_prompt.strip():
+        raise RuntimeError("LLM invocation prompt is required.")
+
+
+def _provider_to_harness(provider: str) -> str:
+    """Derive the CLI harness from the provider for CLI-mode tiers."""
+    return {
+        "anthropic": "claude",
+        "openai": "codex exec",
+        "codex": "codex exec",
+        "minimax": "pi",
+        "google": "pi",
+        "ollama": "ollama",
+    }.get(provider, provider)
+
+
+def _cli_family_to_provider_and_harness(cli_family: str | None) -> tuple[str | None, str | None]:
+    normalized = str(cli_family or "").strip().lower().replace("-", "_")
+    if not normalized:
+        return None, None
+    mapping = {
+        "claude": ("anthropic", "claude"),
+        "claude_code": ("anthropic", "claude"),
+        "codex": ("openai", "codex exec"),
+        "openai": ("openai", "codex exec"),
+        "pi": ("google", "pi"),
+        "gemini": ("google", "pi"),
+        "gemini_cli": ("google", "pi"),
+        "ollama": ("ollama", "ollama"),
+    }
+    return mapping.get(normalized, (None, None))
+
+
+def _resolve_cli_from_tier(
+    tier_cfg: dict[str, Any],
+    provider_override: str | None,
+    model_override: str | None,
+) -> tuple[str, str, str]:
+    """Extract CLI (provider, base_cmd, delivery) from a tier config dict.
+
+    TOML tier keys: cliFamily, cliProfile, apiProvider, base_cmd, delivery.
+    When a CLI family is configured, it is the source of truth for the CLI
+    harness/provider pair; apiProvider remains the API transport provider.
+    """
+    family_provider, _ = _cli_family_to_provider_and_harness(str(tier_cfg.get("cliFamily") or "").strip())
+    provider = _normalize_provider_name(provider_override) or family_provider or _normalize_provider_name(
+        str(tier_cfg.get("apiProvider") or tier_cfg.get("provider") or "").strip()
+    ) or "cli"
+    model = model_override or str(tier_cfg.get("cliProfile") or tier_cfg.get("model") or "").strip() or None
+    base_cmd = str(tier_cfg.get("base_cmd") or "").strip()
+    delivery = str(tier_cfg.get("delivery") or "argument").strip().lower()
+    if base_cmd:
+        base_cmd = normalize_llm_cli_base(base_cmd)
+        base_cmd = _apply_model_flag(base_cmd, model)
+    return provider, base_cmd, delivery
+
+
+def _resolve_invocation(request: LlmInvocationRequest) -> _ResolvedInvocation:
+    if request.strength is not None:
+        # Log explicit strength usage for audit trail.
+        warnings.warn(
+            f"[invoke_llm] purpose={request.purpose!r} strength={request.strength!r}",
+            UserWarning,
+            stacklevel=2,
+        )
+    transport = _resolve_requested_transport(request)
+    delivery_model = _resolve_requested_delivery_model(request)
+    interaction_model = _resolve_requested_interaction_model(request)
+
+    if request.base_cmd is not None or request.delivery is not None:
+        base_cmd = normalize_llm_cli_base(request.base_cmd)
+        delivery = request.delivery
+        provider = _normalize_provider_name(request.provider) or _infer_provider_from_base_cmd(base_cmd) or shlex.split(base_cmd)[0].strip().lower()
+        base_cmd = _apply_model_flag(base_cmd, request.model)
+        return _ResolvedInvocation(
+            transport=transport,
+            delivery_model=delivery_model,
+            interaction_model=interaction_model,
+            provider=provider,
+            base_cmd=base_cmd,
+            delivery=delivery,
+            model=request.model or _extract_model_flag(base_cmd),
+        )
+
+    cfg = _load_global_llm_cfg()
+    strength = request.strength or "medium"
+    tier_cfg = _tier_config(strength, cfg)
+    if tier_cfg is None:
+        provider, base_cmd, delivery = _load_cli_config_from_cfg(
+            cfg,
+            provider_override=request.provider,
+            model_override=request.model,
+        )
+        return _ResolvedInvocation(
+            transport="cli",
+            delivery_model=delivery_model,
+            interaction_model=interaction_model,
+            provider=provider,
+            base_cmd=base_cmd,
+            delivery=delivery,
+            model=request.model or _extract_model_flag(base_cmd),
+        )
+
+    tier_mode = str(tier_cfg.get("mode") or tier_cfg.get("transport") or "cli").strip().lower()
+    if transport == "api":
+        if tier_mode != "api":
+            raise RuntimeError(
+                f"transport='api' requested but no tier configuration provides apiMode for strength={strength!r}. "
+                f"Set tier.{strength}.mode='api' and configure apiProvider + apiModel in the tier config."
+            )
+        tier_provider = _normalize_provider_name(
+            str(tier_cfg.get("apiProvider") or tier_cfg.get("provider") or "").strip()
+        )
+        tier_model = str(tier_cfg.get("apiModel") or tier_cfg.get("model") or "").strip() or None
+        return _ResolvedInvocation(
+            transport="api",
+            delivery_model=delivery_model,
+            interaction_model=interaction_model,
+            provider=tier_provider or "cli",
+            base_cmd="",
+            delivery="",
+            model=request.model or tier_model,
+        )
+
+    provider, base_cmd, delivery = _resolve_cli_from_tier(
+        tier_cfg,
+        provider_override=request.provider,
+        model_override=request.model,
+    )
+    if not base_cmd:
+        cli_profile = str(tier_cfg.get("cliProfile") or "").strip()
+        cli_family = str(tier_cfg.get("cliFamily") or "").strip()
+        family_provider, family_harness = _cli_family_to_provider_and_harness(cli_family)
+        harness_provider = (
+            _normalize_provider_name(request.provider)
+            or family_provider
+            or _normalize_provider_name(str(tier_cfg.get("apiProvider") or provider or "").strip())
+            or provider
+        )
+        harness = family_harness or _provider_to_harness(harness_provider)
+        if cli_profile:
+            # Tier has a cliProfile but no explicit base_cmd — construct from
+            # the configured CLI family when present.
+            if harness == "pi":
+                constructed = f"pi --provider {harness_provider}"
+                resolved_model = request.model or cli_profile
+                constructed = _apply_model_flag(constructed, resolved_model)
+                base_cmd = constructed
+                delivery = "argument"
+            else:
+                constructed = normalize_llm_cli_base(harness)
+                resolved_model = request.model or cli_profile
+                constructed = _apply_model_flag(constructed, resolved_model)
+                base_cmd = constructed
+                delivery = "argument"
+        else:
+            raise RuntimeError(
+                f"Tier {strength!r} is configured but specifies neither base_cmd nor cliProfile "
+                f"— cannot construct a CLI invocation. Configure the tier's cliFamily/cliProfile."
+            )
+    return _ResolvedInvocation(
+        transport="cli",
+        delivery_model=delivery_model,
+        interaction_model=interaction_model,
+        provider=provider,
+        base_cmd=base_cmd,
+        delivery=delivery,
+        model=request.model or _extract_model_flag(base_cmd),
+    )
+
+
+def _evaluate_response_contract(
+    *,
+    response_contract: ResponseContract | None,
+    stdout: str,
+) -> tuple[Any | None, bool | None, str | None]:
+    parsed_json = None
+    contract_ok: bool | None = None
+    contract_error: str | None = None
+    if response_contract == "json_only":
+        parsed_json = _extract_json_payload(stdout)
+        contract_ok = parsed_json is not None
+        if not contract_ok:
+            contract_error = "Expected a JSON object or array response."
+    elif response_contract == "text":
+        contract_ok = True
+    return parsed_json, contract_ok, contract_error
+
+
+def _invoke_provider_api(
+    *,
+    resolved: _ResolvedInvocation,
+    prompt: str,
+    repo_root: Path,
+    timeout_seconds: int | None,
+    response_contract: ResponseContract | None,
+) -> tuple[bool, int, str, str]:
+    if resolved.delivery_model == "streaming":
+        raise NotImplementedError(
+            "invoke_llm API transport does not support delivery_model='streaming' yet. "
+            "Implemented API subset: Anthropic-style, OpenAI, and Google one-shot execution only."
+        )
+    api_shape = canonical_provider_api_shape(resolved.provider)
+    try:
+        if api_shape == "anthropic":
+            if resolved.provider != "anthropic":
+                raise NotImplementedError(
+                    f"Provider {resolved.provider!r} is recognized as using the Anthropic-style API shape, "
+                    "but its provider-specific HTTP wiring is not implemented yet."
+                )
+            settings = load_anthropic_api_settings(
+                repo_root=repo_root,
+                model=resolved.model,
+            )
+            response = anthropic_messages_create(
+                settings=settings,
+                system_prompt="",
+                messages=[{"role": "user", "content": prompt}],
+                tools=[],
+                timeout_seconds=timeout_seconds,
+            )
+            stdout = anthropic_response_text(response)
+        elif api_shape == "openai":
+            settings = load_openai_api_settings(
+                repo_root=repo_root,
+                provider=resolved.provider,
+                model=resolved.model,
+            )
+            response = openai_responses_create(
+                settings=settings,
+                prompt=prompt,
+                timeout_seconds=timeout_seconds,
+                response_contract=response_contract,
+            )
+            stdout = openai_response_text(response)
+        elif api_shape == "google":
+            settings = load_google_api_settings(
+                repo_root=repo_root,
+                model=resolved.model,
+            )
+            response = google_generate_content(
+                settings=settings,
+                prompt=prompt,
+                timeout_seconds=timeout_seconds,
+            )
+            stdout = google_response_text(response)
+        else:
+            raise NotImplementedError(
+                "invoke_llm API transport one-shot mode is implemented for providers "
+                "using the Anthropic, OpenAI, and Google canonical API shapes. "
+                f"Received provider={resolved.provider!r}."
+            )
+    except RuntimeError as exc:
+        return False, 1, "", str(exc)
+    if not stdout:
+        stdout = json.dumps(response, indent=2, sort_keys=True)
+    return True, 0, stdout, ""
+
+
+# Patterns that indicate a retryable rate-limit / resource-exhausted error.
+# Order: most specific first.
+_RATE_LIMIT_PATTERNS = (
+    "RESOURCE_EXHAUSTED",
+    "429",
+    "rate limit",
+    "too many requests",
+    "service unavailable",
+    "overloaded",
+)
+
+
+def _is_rate_limit_failure(stderr: str, stdout: str) -> bool:
+    combined = (stderr + "\n" + stdout).lower()
+    return any(pat.lower() in combined for pat in _RATE_LIMIT_PATTERNS)
+
+
+def _sleep_for(attempt: int) -> None:
+    """Exponential-ish backoff: 1, 2, 4, 10 seconds."""
+    backoffs = (1, 2, 4, 10)
+    import time as _time
+    _time.sleep(backoffs[min(attempt, len(backoffs) - 1)])
+
+
+def invoke_llm(request: LlmInvocationRequest) -> LlmInvocationResult:
+    _validate_request(request)
+    prepared_prompt = _prepare_request_prompt(request)
+    prompt = prepared_prompt.text
+    resolved = _resolve_invocation(request)
+
+    session_id: str | None = None
+    log_path: Path | None = None
+    prompt_characters = len(prompt)
+    prompt_bytes = prepared_prompt.original_bytes
+    cli_cwd = _resolve_cli_cwd(
+        repo_root=request.repo_root,
+        provider=resolved.provider,
+        base_cmd=resolved.base_cmd,
+    ) if resolved.transport == "cli" else request.repo_root
+    used_sanitized_cli_cwd = resolved.transport == "cli" and cli_cwd != request.repo_root
+    if resolved.transport == "api":
+        ok, returncode, stdout, stderr = _invoke_provider_api(
+            resolved=resolved,
+            prompt=prompt,
+            repo_root=request.repo_root,
+            timeout_seconds=request.timeout_seconds,
+            response_contract=request.response_contract,
+        )
+    elif resolved.delivery_model == "streaming":
+        streaming = run_streaming(
+            provider=resolved.provider,
+            base_cmd=resolved.base_cmd,
+            delivery=resolved.delivery,
+            prompt=prompt,
+            cwd=cli_cwd,
+            timeout_s=request.timeout_seconds,
+        )
+        ok = streaming.ok
+        returncode = streaming.returncode
+        stdout = streaming.stdout
+        stderr = streaming.stderr
+        session_id = streaming.session_id
+        log_path = streaming.log_path
+
+        # Retry on rate-limit failures with exponential backoff.
+        if not ok and _is_rate_limit_failure(stderr, stdout):
+            backoff_labels = ("1s", "2s", "4s", "10s")
+            retry_messages: list[str] = []
+            for attempt in range(4):
+                _sleep_for(attempt)
+                retry_messages.append(f"[rate-limit retry {attempt + 1}/{4} after {backoff_labels[attempt]}]")
+                streaming = run_streaming(
+                    provider=resolved.provider,
+                    base_cmd=resolved.base_cmd,
+                    delivery=resolved.delivery,
+                    prompt=prompt,
+                    cwd=cli_cwd,
+                    timeout_s=request.timeout_seconds,
+                )
+                if streaming.ok:
+                    ok = True
+                    returncode = streaming.returncode
+                    stdout = streaming.stdout
+                    stderr = streaming.stderr
+                    session_id = streaming.session_id
+                    log_path = streaming.log_path
+                    break
+                retry_messages.append(f"  still failing (rc={streaming.returncode}): {streaming.stderr[:120]!r}")
+            if not ok:
+                retry_detail = "\n".join(retry_messages)
+                stderr = f"{retry_detail}\n{stderr}"
+    else:
+        one_shot = run_one_shot(
+            base_cmd=resolved.base_cmd,
+            delivery=resolved.delivery,
+            prompt=prompt,
+            cwd=cli_cwd,
+            timeout_seconds=request.timeout_seconds,
+            provider=resolved.provider,
+        )
+        ok = one_shot.ok
+        returncode = one_shot.returncode
+        stdout = one_shot.stdout
+        stderr = one_shot.stderr
+
+        # Retry on rate-limit failures with exponential backoff.
+        if not ok and _is_rate_limit_failure(stderr, stdout):
+            backoff_labels = ("1s", "2s", "4s", "10s")
+            retry_messages: list[str] = []
+            for attempt in range(4):
+                _sleep_for(attempt)
+                retry_messages.append(f"[rate-limit retry {attempt + 1}/{4} after {backoff_labels[attempt]}]")
+                one_shot = run_one_shot(
+                    base_cmd=resolved.base_cmd,
+                    delivery=resolved.delivery,
+                    prompt=prompt,
+                    cwd=cli_cwd,
+                    timeout_seconds=request.timeout_seconds,
+                    provider=resolved.provider,
+                )
+                if one_shot.ok:
+                    ok = True
+                    returncode = one_shot.returncode
+                    stdout = one_shot.stdout
+                    stderr = one_shot.stderr
+                    break
+                retry_messages.append(f"  still failing (rc={one_shot.returncode}): {one_shot.stderr[:120]!r}")
+            if not ok:
+                retry_detail = "\n".join(retry_messages)
+                stderr = f"{retry_detail}\n{stderr}"
+    parsed_json, contract_ok, contract_error = _evaluate_response_contract(
+        response_contract=request.response_contract,
+        stdout=stdout,
+    )
+    return LlmInvocationResult(
+        ok=ok,
+        status="ok" if ok else "error",
+        returncode=returncode,
+        stdout=stdout,
+        stderr=stderr,
+        transport=resolved.transport,
+        delivery_model=resolved.delivery_model,
+        interaction_model=resolved.interaction_model,
+        provider=resolved.provider,
+        purpose=request.purpose,
+        repo_root=request.repo_root,
+        base_cmd=resolved.base_cmd,
+        delivery=resolved.delivery,
+        model=resolved.model,
+        response_contract=request.response_contract,
+        parsed_json=parsed_json,
+        contract_ok=contract_ok,
+        contract_error=contract_error,
+        session_id=session_id,
+        log_path=log_path,
+        prompt_characters=prompt_characters,
+        prompt_bytes=prompt_bytes,
+        effective_prompt_bytes=prepared_prompt.effective_bytes,
+        prompt_was_compacted=prepared_prompt.was_compacted,
+        prompt_artifact_dir=prepared_prompt.artifact_dir,
+        prompt_artifact_count=prepared_prompt.artifact_count,
+        cli_cwd=cli_cwd if resolved.transport == "cli" else None,
+        used_sanitized_cli_cwd=used_sanitized_cli_cwd,
+    )