devflow-engine 1.1.15__tar.gz → 1.1.17__tar.gz

{devflow_engine-1.1.15 → devflow_engine-1.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devflow-engine
-Version: 1.1.15
+Version: 1.1.17
 Summary: DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)
 Author: DevFlow
 License: Proprietary

{devflow_engine-1.1.15 → devflow_engine-1.1.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devflow-engine"
-version = "1.1.15"
+version = "1.1.17"
 description = "DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)"
 readme = "README.md"
 requires-python = ">=3.11"

{devflow_engine-1.1.15 → devflow_engine-1.1.17}/src/devflow_engine/errors/error_solver_dag.py

@@ -130,6 +130,100 @@ def _read_recent_journal(repo_root: Path, *, limit_files: int = 3, max_chars: in
     return {"entries": entries, "summary": summary[-max_chars:]}
 
 
+class WorkspaceDirtyError(RuntimeError):
+    """Raised when a run is asked to start against a non-clean working tree."""
+
+
+_ENGINE_INTERNAL_PREFIXES = (".devflow/",)
+
+
+def _is_source_path(path: str) -> bool:
+    if path.startswith(_ENGINE_INTERNAL_PREFIXES):
+        return False
+    # .pyc and __pycache__/ are regenerated by the running backend
+    # and never belong in a fix commit.
+    if path.endswith(".pyc") or "__pycache__/" in path:
+        return False
+    return True
+
+
+def _git_dirty_paths(repo_root: Path) -> list[str]:
+    cp = subprocess.run(
+        ["git", "-C", str(repo_root), "status", "--porcelain"],
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if cp.returncode != 0:
+        return []
+    raw = [line[3:] for line in (cp.stdout or "").splitlines() if line.strip()]
+    return [p for p in raw if _is_source_path(p)]
+
+
+def _assert_clean_workspace(repo_root: Path, *, error_task_id: str) -> None:
+    """Single-worker invariant: each error-solver run must start clean.
+
+    Why: runs commit their own atomic patch at conclusion (see
+    _commit_resolution). If a run starts with leftover edits from a
+    previous run, the resulting commit collapses multiple errors into
+    one and breaks per-error attribution, cherry-pick, and audit.
+    """
+    dirty = _git_dirty_paths(repo_root)
+    if dirty:
+        raise WorkspaceDirtyError(
+            f"error_task {error_task_id}: refusing to start, repo {repo_root} "
+            f"has {len(dirty)} uncommitted path(s): {dirty[:5]}{'…' if len(dirty) > 5 else ''}"
+        )
+
+
+def _commit_resolution(
+    repo_root: Path,
+    *,
+    error_task_id: str,
+    title: str | None,
+    verification: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Commit working-tree edits made by this run, exclusively.
+
+    Stages explicit paths reported by `git status --porcelain` (never
+    `git add -A` — see project rule). Returns a structured outcome so
+    the journal/portal can link to the commit SHA.
+    """
+    paths = _git_dirty_paths(repo_root)
+    if not paths:
+        return {"committed": False, "reason": "no_changes", "paths": []}
+
+    add = subprocess.run(
+        ["git", "-C", str(repo_root), "add", "--", *paths],
+        text=True, capture_output=True, check=False,
+    )
+    if add.returncode != 0:
+        return {"committed": False, "reason": "add_failed", "stderr": (add.stderr or "")[-1000:]}
+
+    repro_cmd = ""
+    if isinstance(verification, dict):
+        repro_cmd = str(verification.get("repro_run_command") or "")
+    safe_title = (title or "error fix").splitlines()[0][:72]
+    message = (
+        f"fix(error): {safe_title}\n\n"
+        f"error_task_id: {error_task_id}\n"
+        f"resolved_at: {_utc_now_iso()}\n"
+        f"verification: {repro_cmd[:200]}\n"
+    )
+    commit = subprocess.run(
+        ["git", "-C", str(repo_root), "commit", "-m", message, "--no-verify"],
+        text=True, capture_output=True, check=False,
+    )
+    if commit.returncode != 0:
+        return {"committed": False, "reason": "commit_failed", "stderr": (commit.stderr or "")[-1000:]}
+
+    sha = subprocess.run(
+        ["git", "-C", str(repo_root), "rev-parse", "HEAD"],
+        text=True, capture_output=True, check=False,
+    ).stdout.strip()
+    return {"committed": True, "sha": sha, "paths": paths}
+
+
 def _git_changes_since(repo_root: Path, *, unix_ts: int | None) -> dict[str, Any]:
     if not unix_ts:
         return {"summary": "", "commits": []}
@@ -262,6 +356,10 @@ class BuildObservabilityNode(Node):
         repo_root = Path(task_context.event.repo_root)
         error_task_id = task_context.event.error_task_id
 
+        # Single-worker invariant: each run starts clean so its
+        # post-resolve commit isolates this error's changes.
+        _assert_clean_workspace(repo_root, error_task_id=error_task_id)
+
         # Ensure we have a persistor + base context
         persistor: ContextPersistor = task_context.metadata.setdefault(
             "context_persistor", ContextPersistor(repo_root=repo_root, error_task_id=error_task_id)
@@ -423,10 +521,65 @@ class BuildObservabilityNode(Node):
             # - None / legacy → gate-aware stop (pre-1.1.15 behavior).
             if worker_role == "analyst":
                 task_context.stop_workflow()
+                return task_context
             elif worker_role == "fix":
                 pass  # always continue
             elif not gates_passed:
                 task_context.stop_workflow()
+                return task_context
+
+            # Track A: repo-quality LLM judge — pure-LLM gate that runs AFTER
+            # the observation pass and BEFORE FirstPassFix. Closes the leak
+            # where a repro asserts on symbol presence (greppy "found X: True")
+            # rather than observable behavior. The fix worker also runs this
+            # gate — analyst stops above, so we only reach here on roles
+            # {None, "fix"} that are about to advance to FirstPassFix.
+            if gates_passed:
+                judge_fn = funcs.get("repo_quality_judge_fn") if isinstance(funcs, dict) else None
+                if callable(judge_fn):
+                    try:
+                        judgment = judge_fn(context) or {}
+                    except Exception as exc:  # judge transport failure → safe stop
+                        judgment = {
+                            "behavioral_vs_presence": "ambiguous",
+                            "fails_for_described_reason": "unclear",
+                            "rationale": "repo_quality_judge raised",
+                            "judge_ok": False,
+                            "judge_error": str(exc)[:500],
+                        }
+                    persistor.persist(context=context, node_name="RepoQualityJudge", output=judgment)
+
+                    # Persist the judgment to the canonical observability
+                    # sandbox path so the dashboard / portal can render it
+                    # alongside the repro artifact.
+                    quality_dir = repo_root / ".devflow" / "observability" / error_task_id
+                    quality_dir.mkdir(parents=True, exist_ok=True)
+                    (quality_dir / "repo_quality.json").write_text(
+                        json.dumps(judgment, indent=2, sort_keys=True) + "\n",
+                        encoding="utf-8",
+                    )
+
+                    healthy = (
+                        bool(judgment.get("judge_ok", True))
+                        and judgment.get("behavioral_vs_presence") == "behavioral"
+                        and judgment.get("fails_for_described_reason") == "yes"
+                    )
+                    if not healthy:
+                        with store._connect() as conn:
+                            conn.execute(
+                                "UPDATE error_tasks SET quality_status=?, updated_at=? "
+                                "WHERE error_task_id=?",
+                                ("awaiting_quality_review", int(time.time()), error_task_id),
+                            )
+                        task_context.metadata["outcome"] = "awaiting_quality_review"
+                        task_context.metadata["reason"] = (
+                            f"repo_quality: behavioral_vs_presence="
+                            f"{judgment.get('behavioral_vs_presence')!r}, "
+                            f"fails_for_described_reason="
+                            f"{judgment.get('fails_for_described_reason')!r}"
+                        )
+                        task_context.stop_workflow()
+                        return task_context
 
         return task_context
 
@@ -515,7 +668,16 @@ class ResolveNode(Node):
         error_task_id = task_context.event.error_task_id
 
         verification = task_context.metadata.get("verification")
-        verified = bool((verification or {}).get("green_gate"))
+        # Red-before-fix invariant: ResolveNode refuses to mark resolved
+        # unless BuildObservability persisted observable=True at intake.
+        # Closes the "already-green-at-intake" leak — a green-gate True with
+        # no red baseline proves nothing.
+        observation_was_red = False
+        bo = context.get("BuildObservability") if isinstance(context.get("BuildObservability"), dict) else None
+        if isinstance(bo, dict):
+            bo_out = bo.get("output") if isinstance(bo.get("output"), dict) else {}
+            observation_was_red = bool(bo_out.get("observable"))
+        verified = bool((verification or {}).get("green_gate")) and observation_was_red
         runtime_context = context.get("runtimeContext") if isinstance(context.get("runtimeContext"), dict) else None
         prior_runs = context.get("priorRuns") if isinstance(context.get("priorRuns"), dict) else None
         fingerprint = None
@@ -528,6 +690,13 @@ class ResolveNode(Node):
         self.save_output(ResolveNode.OutputType(verified=verified, verification=verification))
 
         if verified:
+            commit_result = _commit_resolution(
+                persistor.repo_root,
+                error_task_id=error_task_id,
+                title=str(title) if title is not None else None,
+                verification=verification,
+            )
+            task_context.metadata["commit_result"] = commit_result
             with store._connect() as conn:
                 conn.execute(
                     "UPDATE error_tasks SET status='resolved', updated_at=? WHERE error_task_id=?",
@@ -543,7 +712,10 @@ class ResolveNode(Node):
                     (int(time.time()), error_task_id),
                 )
             task_context.metadata["outcome"] = "in_progress"
-            task_context.metadata["reason"] = "verification_failed"
+            if not observation_was_red:
+                task_context.metadata["reason"] = "observation_was_not_red_at_intake"
+            else:
+                task_context.metadata["reason"] = "verification_failed"
 
         _append_error_solver_journal(
             repo_root=persistor.repo_root,

devflow_engine-1.1.17/src/devflow_engine/errors/repo_quality_judge.py

@@ -0,0 +1,256 @@
+"""Repro-quality LLM judge for the error-solver DAG (Track A).
+
+Scores a reproduction artifact along two dimensions BEFORE FirstPassFix runs:
+
+  - behavioral_vs_presence: does the repro assert observable behavior, or
+    does it merely check that a symbol exists in the codebase?
+  - fails_for_described_reason: does the failure produced by the repro
+    match the bug-report symptom described by the user?
+
+Failure mode in the wild: LLM-authored repros that grep for a string
+("last_login_at found in User model: True") pass the boolean green-gate
+oracle while proving nothing about the actual bug. This judge catches
+those cases at intake.
+
+The judge is PURE LLM — no regex / heuristic fallback. Per project rule
+(feedback_no_regex_first): never propose regex-first content classification.
+The configured medium-tier provider (MiniMax) is the source of truth
+(feedback_no_provider_swap_suggestions).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, ValidationError
+
+from ..llm.invoke import LlmInvocationRequest, invoke_llm
+
+BehavioralVsPresence = Literal["behavioral", "presence", "ambiguous"]
+FailsForDescribedReason = Literal["yes", "no", "unclear"]
+
+
+class RepoQualityJudgment(BaseModel):
+    behavioral_vs_presence: BehavioralVsPresence
+    fails_for_described_reason: FailsForDescribedReason
+    rationale: str = Field(default="")
+    judge_ok: bool = Field(default=True)
+    judge_error: str | None = Field(default=None)
+
+    def is_healthy(self) -> bool:
+        """Both dimensions must be green for the DAG to advance to fix."""
+        return (
+            self.judge_ok
+            and self.behavioral_vs_presence == "behavioral"
+            and self.fails_for_described_reason == "yes"
+        )
+
+
+_PROMPT_INSTRUCTIONS = """\
+You are auditing a bug reproduction (repro) script before any fix is attempted.
+
+You are given:
+  - the user's bug report (title, message, expected_behavior, steps_to_reproduce)
+  - the repro artifact: its source code and the path where it was written
+
+Score the repro on TWO dimensions:
+
+1. behavioral_vs_presence  ∈ {behavioral, presence, ambiguous}
+   - "behavioral"  → the repro executes the system and asserts on observable
+                     behavior (HTTP response, DB row state after an action,
+                     function return value, raised exception, log entry).
+   - "presence"    → the repro merely checks that a symbol / string / file
+                     exists in the codebase. Examples that are "presence":
+                       * grep for a field name in a model file
+                       * `assert "last_login_at" in open("user.py").read()`
+                       * importing a module and asserting an attribute exists
+                     These prove nothing about the bug — they pass on the
+                     string match even when behavior is still broken.
+   - "ambiguous"   → mixed / cannot tell from the artifact alone.
+
+2. fails_for_described_reason ∈ {yes, no, unclear}
+   - "yes"     → the failure mode the repro produces, when run against the
+                 current code, would manifest as the symptom the user described.
+   - "no"      → the repro fails for an unrelated reason (e.g. ImportError,
+                 missing fixture, wrong assertion target).
+   - "unclear" → cannot determine without running it.
+
+Return STRICT JSON with these exact keys:
+{
+  "behavioral_vs_presence": "<behavioral|presence|ambiguous>",
+  "fails_for_described_reason": "<yes|no|unclear>",
+  "rationale": "<one or two sentences citing the specific code patterns you saw>"
+}
+
+No prose outside the JSON. No code fences. No additional keys.
+"""
+
+
+def _read_repro_artifact(repo_root: Path, error_task_id: str) -> tuple[str | None, str | None]:
+    """Look for the repro artifact in the canonical user-report observability sandbox.
+
+    Returns (path_str, source_text) or (None, None) if absent.
+    """
+    base = repo_root / ".devflow" / "observability" / error_task_id
+    for ext in ("py", "test.ts", "test.tsx"):
+        candidate = base / f"repro.{ext}"
+        if candidate.exists():
+            try:
+                return str(candidate), candidate.read_text(encoding="utf-8")
+            except OSError:
+                return str(candidate), None
+    return None, None
+
+
+def _build_prompt_payload(
+    *,
+    bug_report: dict[str, Any],
+    observation: dict[str, Any] | None,
+    repro_path: str | None,
+    repro_source: str | None,
+) -> dict[str, Any]:
+    return {
+        "instructions": _PROMPT_INSTRUCTIONS,
+        "bug_report": {
+            "title": bug_report.get("title"),
+            "message": bug_report.get("message"),
+            "expected_behavior": bug_report.get("expected_behavior"),
+            "steps_to_reproduce": bug_report.get("steps_to_reproduce") or [],
+            "report_context": bug_report.get("report_context") or {},
+        },
+        "observation_summary": {
+            "summary": (observation or {}).get("summary"),
+            "likely_location": (observation or {}).get("likely_location"),
+            "repro_run_command": (observation or {}).get("repro_run_command"),
+        },
+        "repro_artifact": {
+            "path": repro_path,
+            "source": repro_source,
+        },
+    }
+
+
+def _persist_judgment(
+    *,
+    repo_root: Path,
+    error_task_id: str,
+    judgment: RepoQualityJudgment,
+) -> Path:
+    out_dir = repo_root / ".devflow" / "observability" / error_task_id
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "repo_quality.json"
+    out_path.write_text(
+        json.dumps(judgment.model_dump(), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return out_path
+
+
+def judge_repro_quality(
+    *,
+    repo_root: Path,
+    error_task_id: str,
+    bug_report: dict[str, Any],
+    observation: dict[str, Any] | None = None,
+    repro_path: str | None = None,
+    repro_source: str | None = None,
+) -> RepoQualityJudgment:
+    """Run the LLM judge over a repro artifact and persist the judgment.
+
+    Pure LLM — no fallback heuristics. If the LLM call fails or returns
+    unparseable JSON, the judgment is marked judge_ok=False and dimensions
+    fall back to the safe-stop default (ambiguous / unclear) so the DAG
+    holds for human review rather than advancing on weak evidence.
+    """
+    repo_root = Path(repo_root)
+    if repro_path is None and repro_source is None:
+        repro_path, repro_source = _read_repro_artifact(repo_root, error_task_id)
+
+    payload = _build_prompt_payload(
+        bug_report=bug_report,
+        observation=observation,
+        repro_path=repro_path,
+        repro_source=repro_source,
+    )
+
+    request = LlmInvocationRequest(
+        purpose="error_solver.repo_quality_judge",
+        repo_root=repo_root,
+        prompt="",
+        prompt_payload=payload,
+        strength="medium",
+        response_contract="json_only",
+        interaction_model="request_response",
+        timeout_seconds=180,
+    )
+
+    try:
+        result = invoke_llm(request)
+    except Exception as exc:  # pragma: no cover — surface-level transport failures
+        judgment = RepoQualityJudgment(
+            behavioral_vs_presence="ambiguous",
+            fails_for_described_reason="unclear",
+            rationale="judge invocation failed",
+            judge_ok=False,
+            judge_error=str(exc)[:500],
+        )
+        _persist_judgment(repo_root=repo_root, error_task_id=error_task_id, judgment=judgment)
+        return judgment
+
+    parsed: Any = result.parsed_json
+    if parsed is None or not isinstance(parsed, dict):
+        judgment = RepoQualityJudgment(
+            behavioral_vs_presence="ambiguous",
+            fails_for_described_reason="unclear",
+            rationale="judge response was not JSON object",
+            judge_ok=False,
+            judge_error=(result.contract_error or "non-json response")[:500],
+        )
+        _persist_judgment(repo_root=repo_root, error_task_id=error_task_id, judgment=judgment)
+        return judgment
+
+    try:
+        judgment = RepoQualityJudgment(
+            behavioral_vs_presence=parsed.get("behavioral_vs_presence"),
+            fails_for_described_reason=parsed.get("fails_for_described_reason"),
+            rationale=str(parsed.get("rationale") or ""),
+            judge_ok=True,
+            judge_error=None,
+        )
+    except ValidationError as exc:
+        judgment = RepoQualityJudgment(
+            behavioral_vs_presence="ambiguous",
+            fails_for_described_reason="unclear",
+            rationale="judge response failed schema validation",
+            judge_ok=False,
+            judge_error=str(exc)[:500],
+        )
+
+    _persist_judgment(repo_root=repo_root, error_task_id=error_task_id, judgment=judgment)
+    return judgment
+
+
+def build_default_repo_quality_judge_fn(
+    *,
+    repo_root: Path,
+    error_task_id: str,
+) -> "callable":
+    """Factory that closes over repo_root/etid so callers can pass a single
+    (context) → judgment function into the error-solver runtime."""
+
+    def _fn(context: dict[str, Any]) -> dict[str, Any]:
+        runtime_context = context.get("runtimeContext") if isinstance(context.get("runtimeContext"), dict) else {}
+        user_report = runtime_context.get("user_report") if isinstance(runtime_context.get("user_report"), dict) else {}
+        observability = context.get("BuildObservability") if isinstance(context.get("BuildObservability"), dict) else {}
+        out = observability.get("output") if isinstance(observability.get("output"), dict) else {}
+        observation = out.get("observation") if isinstance(out.get("observation"), dict) else None
+        judgment = judge_repro_quality(
+            repo_root=repo_root,
+            error_task_id=error_task_id,
+            bug_report=user_report,
+            observation=observation,
+        )
+        return judgment.model_dump()
+
+    return _fn

devflow_engine-1.1.17/src/devflow_engine/errors/vision.py

@@ -0,0 +1,138 @@
+"""Image-aware vision queries via the configured vision tier.
+
+Pi (medium tier, MiniMax) cannot see images. When a clarify-chat
+submitter attaches a screenshot, pi calls this helper through its
+``ask_about_image`` extension tool to ask a specific question about
+the image. The vision tier (``tier.vision`` in the engine's baked
+``~/.devflow/config.toml`` — typically gpt-5.3-codex) sees the image
+content directly and returns a focused text answer.
+
+One image, one question, one round-trip. Pi can call this multiple
+times if it has multiple questions about the same image.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import mimetypes
+from pathlib import Path
+
+
+logger = logging.getLogger(__name__)
+
+
+_MAX_IMAGE_BYTES = 10 * 1024 * 1024  # 10 MB
+_ALLOWED_MIME_PREFIXES = ("image/",)
+_VISION_TIMEOUT_SECONDS = 120
+
+
+class VisionError(RuntimeError):
+    """Wraps any failure path so callers (sidecar route, pi extension)
+    get a stable error class instead of bare RuntimeError."""
+
+
+def _read_image_as_data_url(path: Path) -> str:
+    """Read the file from disk and encode as a data URL the Responses
+    API accepts directly (no separate file-upload round-trip)."""
+    if not path.is_file():
+        raise VisionError(f"image_not_found: {path}")
+    size = path.stat().st_size
+    if size > _MAX_IMAGE_BYTES:
+        raise VisionError(
+            f"image_too_large: {size} bytes > {_MAX_IMAGE_BYTES} cap"
+        )
+    mime, _ = mimetypes.guess_type(str(path))
+    if not mime or not mime.startswith(_ALLOWED_MIME_PREFIXES):
+        raise VisionError(f"image_bad_mime: {mime!r} (not image/*)")
+    data = path.read_bytes()
+    b64 = base64.b64encode(data).decode("ascii")
+    return f"data:{mime};base64,{b64}"
+
+
+def invoke_image_query(
+    *,
+    repo_root: Path,
+    image_path: Path,
+    question: str,
+) -> str:
+    """Ask the vision tier one focused question about one image.
+
+    Returns the assistant's plain-text answer. Raises VisionError on
+    any setup/IO/auth failure; raises through the underlying LLM
+    exception on provider failure.
+
+    Pi's extension prompt encourages ONE focused question per call
+    rather than 'describe the image' — the latter wastes context and
+    invites the model to invent details. Examples that work well:
+      'what error text is visible in this screenshot?'
+      'what colour is the highlighted button in the upper right?'
+      'is the Submit button enabled or greyed out?'
+    """
+    if not question.strip():
+        raise VisionError("question_empty")
+
+    # Local imports — keep module cheap on non-vision paths.
+    from ..llm.invoke import _load_global_llm_cfg, _tier_config
+    from ..llm.provider_api import (
+        load_openai_api_settings,
+        openai_response_text,
+        openai_responses_create,
+    )
+
+    data_url = _read_image_as_data_url(image_path)
+
+    # Resolve tier.vision config directly — invoke_llm doesn't have a
+    # content-blocks path (it's prompt:str-only), so we go straight to
+    # the provider helper with the resolved settings.
+    cfg = _load_global_llm_cfg()
+    tier = _tier_config("vision", cfg)
+    if not tier:
+        raise VisionError(
+            "vision_tier_not_configured: add [tiers.vision] with "
+            "mode='api', apiProvider='openai', apiModel='gpt-5.3-codex' "
+            "to ~/.devflow/config.toml"
+        )
+    provider = str(tier.get("apiProvider") or "openai").strip().lower()
+    if provider != "openai":
+        raise VisionError(
+            f"vision_tier_bad_provider: {provider!r} (only 'openai' supported)"
+        )
+    model = str(tier.get("apiModel") or "gpt-5.3-codex").strip()
+
+    settings = load_openai_api_settings(
+        repo_root=repo_root, provider="openai", model=model,
+    )
+
+    content_blocks = [
+        {"type": "input_image", "image_url": data_url, "detail": "auto"},
+        {
+            "type": "input_text",
+            "text": (
+                "You are answering a single targeted question about the "
+                "image above on behalf of an automated bug-triage agent. "
+                "Be precise and concise — your answer feeds back into a "
+                "downstream LLM that needs facts, not flowery prose. If "
+                "the image doesn't contain the information needed to "
+                "answer, say so plainly.\n\n"
+                f"Question: {question.strip()}"
+            ),
+        },
+    ]
+
+    logger.info(
+        "vision: invoking %s image=%s question_chars=%d",
+        model, image_path.name, len(question),
+    )
+    try:
+        response = openai_responses_create(
+            settings=settings,
+            content_blocks=content_blocks,
+            timeout_seconds=_VISION_TIMEOUT_SECONDS,
+        )
+    except RuntimeError as exc:
+        raise VisionError(f"vision_provider_error: {exc}") from exc
+    answer = openai_response_text(response).strip()
+    if not answer:
+        raise VisionError("vision_empty_response")
+    return answer

{devflow_engine-1.1.15 → devflow_engine-1.1.17}/src/devflow_engine/llm/provider_api.py

@@ -332,14 +332,33 @@ def _openai_text_format_for_response_contract(response_contract: str | None) ->
 def openai_responses_create(
     *,
     settings: OpenAiApiSettings,
-    prompt: str,
+    prompt: str | None = None,
+    content_blocks: list[dict[str, Any]] | None = None,
     timeout_seconds: int | None,
     response_contract: str | None = None,
 ) -> dict[str, Any]:
-    payload: dict[str, Any] = {
-        "model": settings.model,
-        "input": prompt,
-    }
+    """Call OpenAI's Responses API.
+
+    Two input shapes:
+    - ``prompt=<str>`` (legacy / default text-only): packed as
+      ``input: <str>`` per OpenAI's documented shorthand.
+    - ``content_blocks=[{...}]`` (vision / multimodal): packed as
+      ``input: [{role: 'user', content: [<blocks>]}]`` per the
+      Responses API content-array spec. Each block is a dict with at
+      least ``type`` ('input_text' or 'input_image'); image blocks
+      use ``image_url`` (data URL or HTTPS URL).
+
+    Callers must supply exactly one of the two; we raise otherwise."""
+    if (prompt is None) == (content_blocks is None):
+        raise ValueError(
+            "openai_responses_create: provide exactly one of prompt= or content_blocks="
+        )
+
+    payload: dict[str, Any] = {"model": settings.model}
+    if content_blocks is not None:
+        payload["input"] = [{"role": "user", "content": content_blocks}]
+    else:
+        payload["input"] = prompt
     text_format = _openai_text_format_for_response_contract(response_contract)
     if text_format is not None:
         payload["text"] = text_format