devops-bot-sdk 1.4.96__tar.gz → 1.4.101__tar.gz

{devops_bot_sdk-1.4.96 → devops_bot_sdk-1.4.101}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.4.96
+Version: 1.4.101
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.4.96 → devops_bot_sdk-1.4.101}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.4.96
+Version: 1.4.101
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.4.96 → devops_bot_sdk-1.4.101}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -24,6 +24,12 @@ sdk/collectors/__init__.py
 sdk/collectors/files.py
 sdk/collectors/process.py
 sdk/collectors/screenshot.py
+sdk/design_verify/__init__.py
+sdk/design_verify/assets.py
+sdk/design_verify/bootstrap.py
+sdk/design_verify/browser.py
+sdk/design_verify/compare.py
+sdk/design_verify/loop.py
 sdk/hooks/__init__.py
 sdk/hooks/crucial_guard.py
 sdk/ipc/__init__.py

{devops_bot_sdk-1.4.96 → devops_bot_sdk-1.4.101}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devops-bot-sdk"
-version = "1.4.96"
+version = "1.4.101"
 description = "DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{devops_bot_sdk-1.4.96 → devops_bot_sdk-1.4.101}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.4.96
+Version: 1.4.101
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -30,7 +30,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.4.96"
+__version__ = "1.4.101"
 __author__  = "AgentOS"
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.4.96 → devops_bot_sdk-1.4.101}/sdk/client.py

@@ -58,7 +58,7 @@ def _notify_status(task_id: str, status: str) -> None:
             pass
 
 
-SDK_VERSION    = "1.4.96"
+SDK_VERSION    = "1.4.101"
 _POLL_INTERVAL = 3.0
 _POLL_TIMEOUT  = 600.0
 _ORCHESTRATE_TIMEOUT      = 2700.0  # 45 min — covers approval wait + VPS execution time
@@ -195,6 +195,27 @@ class BackendClient:
         _check_status(resp.status_code, self._base_url)
         return [ThreadSummary(**t) for t in resp.json().get("threads", [])]
 
+    # ── Design image (for local visual verification) ───────────────────
+
+    async def fetch_design_image(
+        self, jira_task_id: str,
+    ) -> tuple[bytes, str] | None:
+        """GET /api/v1/orchestrate/design-image/{jira_task_id}.
+
+        Returns the task's design screenshot as ``(bytes, mime_type)``, or
+        ``None`` when the task has no image attachment (backend 404). The backend
+        proxies the bytes from Jira (Atlassian auth lives there, not here). The
+        caller is responsible for treating the bytes as EPHEMERAL — see
+        ``sdk.design_verify.ephemeral_design_image``.
+        """
+        url = self._url(f"/api/v1/orchestrate/design-image/{jira_task_id}")
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.get(url, headers=self._headers)
+        if resp.status_code == 404:
+            return None
+        _check_status(resp.status_code, self._base_url)
+        return resp.content, resp.headers.get("content-type", "image/png")
+
     # ── Orchestrator ──────────────────────────────────────────────────
 
     async def orchestrator_run(

devops_bot_sdk-1.4.101/sdk/design_verify/__init__.py

@@ -0,0 +1,56 @@
+"""Visual design verification & refinement loop (prototype).
+
+Why this exists
+---------------
+Design-to-code fidelity is capped when the system generates a frontend ONCE
+from a JIRA screenshot and never *looks* at what it built. This package closes
+that loop:
+
+    generate -> render in a real browser -> screenshot -> compare against the
+    original design -> feed the differences back -> correct -> repeat.
+
+It is deliberately decoupled from the main pipeline (nothing here is imported by
+the live `handlers`/`local_exec` flow yet) so it can be developed and tested in
+isolation, then slotted into `_code_one_repo` once proven.
+
+Two external pieces it leans on — both already available, no new Python deps:
+
+* ``agent-browser`` — Vercel Labs' Rust browser-automation CLI. Renders the
+  generated UI in headless Chrome and screenshots it. Install separately; see
+  ``README.md``. This is the ONLY new tool requirement.
+* the local ``claude`` CLI — reused via :func:`sdk.local_exec.run_claude_local`.
+  Its built-in ``Read`` tool reads image files natively, so it doubles as the
+  vision model that diffs the two screenshots. No `anthropic`/`openai` package
+  is added.
+
+What the caller must supply
+---------------------------
+The one input this repo does not currently receive is the **original design
+image** (the JIRA attachment). The backend hydrates task *text* only — attachment
+URLs never reach the SDK today (see ``sdk/models/requests.py``). To use this
+loop, the backend/operator must provide a local path to that screenshot. That
+integration is out of scope for this prototype; the loop takes the path as an
+argument.
+"""
+from __future__ import annotations
+
+from .assets import ephemeral_design_image
+from .bootstrap import BootstrapResult, ensure_agent_browser
+from .browser import BrowserError, DiffResult, diff_baseline, render_screenshot, snapshot
+from .compare import ComparisonReport, compare_design
+from .loop import RefinementResult, verify_and_refine
+
+__all__ = [
+    "render_screenshot",
+    "snapshot",
+    "diff_baseline",
+    "DiffResult",
+    "BrowserError",
+    "compare_design",
+    "ComparisonReport",
+    "verify_and_refine",
+    "RefinementResult",
+    "ensure_agent_browser",
+    "BootstrapResult",
+    "ephemeral_design_image",
+]

devops_bot_sdk-1.4.101/sdk/design_verify/assets.py

@@ -0,0 +1,59 @@
+"""Ephemeral handling of the design image fetched from the backend.
+
+The JIRA design screenshot is downloaded from the backend proxy
+(``BackendClient.fetch_design_image``) only for the duration of a verification
+run and MUST NOT be persisted — same rule as the render/diff screenshots. This
+module writes it to an OS temp file and deletes it on exit.
+"""
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from typing import AsyncIterator
+
+
+def _ext_for_mime(mime: str) -> str:
+    m = (mime or "").lower()
+    if "png" in m:
+        return ".png"
+    if "jpeg" in m or "jpg" in m:
+        return ".jpg"
+    if "webp" in m:
+        return ".webp"
+    return ".img"
+
+
+@contextlib.asynccontextmanager
+async def ephemeral_design_image(client, jira_task_id: str) -> AsyncIterator[str | None]:
+    """Download a task's design image to a temp file for the duration of a `with`.
+
+    Yields the local path, or ``None`` when the task has no design image. The
+    file is deleted on exit no matter what — the design image is never persisted.
+
+    ``client`` is a ``BackendClient`` (anything exposing
+    ``async fetch_design_image(jira_task_id) -> (bytes, mime) | None``).
+
+    Example::
+
+        async with ephemeral_design_image(client, task_id) as design_path:
+            if design_path is None:
+                ...  # no design attached — skip visual verification
+            else:
+                await verify_and_refine(design_path=design_path, ...)
+    """
+    img = await client.fetch_design_image(jira_task_id)
+    if not img:
+        yield None
+        return
+    data, mime = img
+    fd, path = tempfile.mkstemp(prefix="agentos_design_", suffix=_ext_for_mime(mime))
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        yield path
+    finally:
+        try:
+            os.remove(path)
+        except OSError:
+            pass

devops_bot_sdk-1.4.101/sdk/design_verify/bootstrap.py

@@ -0,0 +1,170 @@
+"""Per-user, on-demand installation of the ``agent-browser`` CLI.
+
+Why this lives in the SDK
+-------------------------
+The visual verification loop renders and screenshots the generated frontend, and
+that generation runs on the USER'S machine (the default `claude_code` engine runs
+the local `claude` CLI locally — the backend only plans). So `agent-browser` must
+be present on every user's system, not on the backend server.
+
+`agent-browser` is a native Rust binary, not a pip package, so it cannot ride
+along with ``pip install devops-bot-sdk``. Instead we bootstrap it lazily on
+first use: check if it's already there, otherwise install it via the best channel
+available on this machine, then fetch Chrome for Testing once. The whole thing is
+idempotent and cached, and it NEVER hard-fails the SDK — if install isn't
+possible (locked-down box, no package manager), it returns a reason and the
+caller degrades to the text-only path.
+
+Design choices
+--------------
+* **Lazy, not install-time.** A hard dependency at ``pip install`` time would
+  break every user on a machine without a Rust/Node toolchain or network. Lazy +
+  graceful-degrade keeps the SDK installable everywhere.
+* **Cached.** A marker file under ``~/.agentos`` means the (subprocess-heavy)
+  checks run once, then it's a fast no-op on every subsequent run.
+* **Opt-outable.** ``AGENTOS_ENABLE_DESIGN_VERIFY=0`` disables all of this.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+_BINARY = "agent-browser"
+_MARKER = Path.home() / ".agentos" / ".agent_browser_ready"
+# Installs pull binaries / Chrome over the network — give them real headroom.
+_INSTALL_TIMEOUT_S = 600.0
+_QUICK_TIMEOUT_S = 60.0
+
+
+@dataclass
+class BootstrapResult:
+    ok: bool
+    path: str | None          # resolved agent-browser path when ok
+    reason: str               # human-readable outcome (why it failed, if not ok)
+    installed: bool = False   # True if we actually installed something this call
+
+
+def _run(cmd: list[str], timeout: float) -> tuple[bool, str]:
+    """Run a setup command; return (success, combined-output). Never raises."""
+    try:
+        proc = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout,
+        )
+    except FileNotFoundError:
+        return False, f"{cmd[0]} not found"
+    except subprocess.TimeoutExpired:
+        return False, f"{' '.join(cmd)} timed out after {timeout:.0f}s"
+    except Exception as exc:  # noqa: BLE001 — setup must never crash the SDK
+        return False, str(exc)
+    out = (proc.stdout or "") + (proc.stderr or "")
+    return proc.returncode == 0, out.strip()
+
+
+def _disabled() -> bool:
+    return os.getenv("AGENTOS_ENABLE_DESIGN_VERIFY", "1").lower() in ("0", "false", "no")
+
+
+def _install_binary() -> tuple[bool, str]:
+    """Install the agent-browser binary via the best available channel.
+
+    Order: npm (Node is almost always present — it's how the `claude` CLI itself
+    is installed), then Homebrew on macOS, then Cargo. Each is tried only if its
+    package manager exists. Prebuilt-binary download is intentionally omitted here
+    (GitHub release asset plumbing) — document it as the manual fallback.
+    """
+    attempts: list[str] = []
+
+    if shutil.which("npm"):
+        ok, out = _run(["npm", "install", "-g", _BINARY], _INSTALL_TIMEOUT_S)
+        if ok and shutil.which(_BINARY):
+            return True, "installed via npm"
+        attempts.append(f"npm: {out[-200:]}")
+
+    if sys.platform == "darwin" and shutil.which("brew"):
+        ok, out = _run(["brew", "install", _BINARY], _INSTALL_TIMEOUT_S)
+        if ok and shutil.which(_BINARY):
+            return True, "installed via brew"
+        attempts.append(f"brew: {out[-200:]}")
+
+    if shutil.which("cargo"):
+        ok, out = _run(["cargo", "install", _BINARY], _INSTALL_TIMEOUT_S)
+        if ok and shutil.which(_BINARY):
+            return True, "installed via cargo"
+        attempts.append(f"cargo: {out[-200:]}")
+
+    if not attempts:
+        return False, (
+            "no supported installer found (need npm, brew, or cargo). Install "
+            f"`{_BINARY}` manually — see sdk/design_verify/README.md."
+        )
+    return False, "install attempts failed -> " + " | ".join(attempts)
+
+
+def _ensure_chrome() -> tuple[bool, str]:
+    """Ensure Chrome for Testing is present (`agent-browser install`)."""
+    # `doctor` reports daemon/browser state; if Chrome is already there this is fast.
+    ok, out = _run([_BINARY, "doctor"], _QUICK_TIMEOUT_S)
+    if ok and "chrome" in out.lower() and "not" not in out.lower():
+        return True, "chrome already present"
+    cmd = [_BINARY, "install"]
+    if sys.platform.startswith("linux"):
+        cmd.append("--with-deps")  # pull system libs Chrome needs on Linux
+    ok, out = _run(cmd, _INSTALL_TIMEOUT_S)
+    return ok, out[-200:] if out else ("chrome installed" if ok else "chrome install failed")
+
+
+def ensure_agent_browser(*, force: bool = False) -> BootstrapResult:
+    """Make ``agent-browser`` usable on this machine; idempotent and cached.
+
+    Returns a :class:`BootstrapResult`. On success ``path`` is the binary location.
+    Never raises — callers gate the verification loop on ``result.ok``.
+    """
+    if _disabled():
+        return BootstrapResult(False, None, "design verification disabled "
+                               "(AGENTOS_ENABLE_DESIGN_VERIFY=0)")
+
+    existing = shutil.which(_BINARY)
+    if existing and _MARKER.exists() and not force:
+        return BootstrapResult(True, existing, "already bootstrapped (cached)")
+
+    installed = False
+    if not existing:
+        ok, reason = _install_binary()
+        if not ok:
+            return BootstrapResult(False, None, reason)
+        installed = True
+        existing = shutil.which(_BINARY)
+
+    chrome_ok, chrome_reason = _ensure_chrome()
+    if not chrome_ok:
+        return BootstrapResult(False, existing,
+                               f"agent-browser installed but Chrome setup failed: {chrome_reason}",
+                               installed=installed)
+
+    try:
+        _MARKER.parent.mkdir(parents=True, exist_ok=True)
+        _MARKER.write_text("ok")
+    except OSError:
+        pass  # marker is an optimization; not being able to write it is harmless
+
+    return BootstrapResult(True, existing, "ready", installed=installed)
+
+
+def main() -> int:
+    """CLI entry point: ``python -m sdk.design_verify.bootstrap``.
+
+    Lets ops/onboarding provision agent-browser for a user ahead of time instead
+    of waiting for the first design ticket.
+    """
+    res = ensure_agent_browser(force="--force" in sys.argv)
+    print(f"agent-browser: {'OK' if res.ok else 'UNAVAILABLE'} — {res.reason}"
+          + (f" ({res.path})" if res.path else ""))
+    return 0 if res.ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devops_bot_sdk-1.4.101/sdk/design_verify/browser.py

@@ -0,0 +1,195 @@
+"""Thin async wrapper around the ``agent-browser`` CLI.
+
+Only the two operations the verification loop needs are exposed: render a URL and
+screenshot it to a file, and grab a structured accessibility snapshot. The
+daemon that ``agent-browser`` runs behind the scenes starts on first command and
+persists between calls, so successive screenshots in a refinement loop are cheap.
+
+Command syntax mirrors the upstream CLI (vercel-labs/agent-browser):
+
+    agent-browser open <url>          # navigate (aliases: navigate, goto)
+    agent-browser screenshot <path>   # --full, --screenshot-format png|jpeg
+    agent-browser snapshot --json     # accessibility tree with @e refs
+"""
+from __future__ import annotations
+
+import asyncio
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+_BINARY = "agent-browser"
+# A single browser op should never hang the loop; the daemon is local.
+_CMD_TIMEOUT_S = 60.0
+
+# agent-browser's `diff screenshot` prints human-readable lines; parse defensively
+# rather than assume a stable JSON shape. Captures "12.34%" and "1234 pixels".
+_PCT_RE = re.compile(r"([\d.]+)\s*%")
+_PIXELS_RE = re.compile(r"([\d,]+)\s*(?:different\s+)?pixels", re.IGNORECASE)
+
+
+class BrowserError(RuntimeError):
+    """Raised when the agent-browser CLI is missing or a command fails."""
+
+
+@dataclass
+class DiffResult:
+    """Outcome of a native `agent-browser diff screenshot` pixel comparison."""
+    mismatch_pct: float | None       # None when a pixel % could not be determined
+    diff_pixels: int | None
+    diff_image: str | None           # path to the red-highlighted diff image
+    dimension_mismatch: bool         # baseline/current sizes differ -> no pixel diff
+    raw: str = ""
+
+
+def is_available() -> bool:
+    """True if the ``agent-browser`` binary is on PATH."""
+    return shutil.which(_BINARY) is not None
+
+
+async def _run(*args: str) -> str:
+    """Run one agent-browser subcommand, returning stdout (text)."""
+    if not is_available():
+        raise BrowserError(
+            f"`{_BINARY}` not found on PATH. Install it (see "
+            "sdk/design_verify/README.md) — it is the only external dependency "
+            "of the design verification loop."
+        )
+    proc = await asyncio.create_subprocess_exec(
+        _BINARY, *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    try:
+        out, err = await asyncio.wait_for(proc.communicate(), timeout=_CMD_TIMEOUT_S)
+    except asyncio.TimeoutError as exc:  # pragma: no cover - defensive
+        proc.kill()
+        raise BrowserError(f"`{_BINARY} {args[0]}` timed out after {_CMD_TIMEOUT_S}s") from exc
+    if proc.returncode != 0:
+        raise BrowserError(
+            f"`{_BINARY} {' '.join(args)}` failed (exit {proc.returncode}): "
+            f"{err.decode(errors='replace').strip()}"
+        )
+    return out.decode(errors="replace")
+
+
+async def render_screenshot(
+    url: str,
+    out_path: str | Path,
+    *,
+    full_page: bool = False,
+    fmt: str = "png",
+) -> Path:
+    """Navigate to ``url`` and screenshot it to ``out_path``.
+
+    ``full_page`` captures the entire scrollable page (``--full``); the default
+    captures just the viewport, which usually matches a design mock's framing
+    better. Returns the resolved output path.
+    """
+    out = Path(out_path).expanduser().resolve()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    await _run("open", url)
+    args = ["screenshot", str(out), "--screenshot-format", fmt]
+    if full_page:
+        args.append("--full")
+    await _run(*args)
+    if not out.exists():
+        raise BrowserError(f"screenshot reported success but {out} was not written")
+    return out
+
+
+async def snapshot(url: str | None = None, *, interactive_only: bool = False) -> str:
+    """Return the page's accessibility tree as JSON text.
+
+    Lets the comparison assert *structure* (roles, labels, hierarchy) — not just
+    pixels. If ``url`` is given, navigates first; otherwise snapshots the current
+    page. Useful as a secondary signal when a pixel diff is ambiguous.
+    """
+    if url:
+        await _run("open", url)
+    args = ["snapshot", "--json"]
+    if interactive_only:
+        args.append("--interactive")
+    return await _run(*args)
+
+
+async def diff_baseline(
+    baseline: str | Path,
+    *,
+    out_path: str | Path,
+    url: str | None = None,
+    threshold: float = 0.1,
+) -> DiffResult:
+    """Pixel-diff the current page against a ``baseline`` image.
+
+    Runs ``agent-browser diff screenshot --baseline <baseline> -o <out> -t <thr>``,
+    which screenshots the live page and compares it to ``baseline`` at the pixel
+    level, writing a red-highlighted diff image to ``out_path``. If ``url`` is
+    given, navigates there first.
+
+    This is a *quantitative, localizing* signal — mismatch % and a highlight
+    image — NOT a semantic judgement. Baselines whose dimensions differ from the
+    render yield ``dimension_mismatch=True`` (the CLI refuses a pixel compare);
+    that is expected for design mocks and is handled gracefully by the caller,
+    which falls back to the vision comparison.
+
+    A nonzero exit here means "differences found," not failure, so — unlike the
+    other commands — we do not raise on it; we parse the reported metrics.
+    """
+    if not is_available():
+        raise BrowserError(
+            f"`{_BINARY}` not found on PATH. Install it (see "
+            "sdk/design_verify/README.md)."
+        )
+    base = Path(baseline).expanduser().resolve()
+    if not base.exists():
+        raise BrowserError(f"baseline image not found: {base}")
+    out = Path(out_path).expanduser().resolve()
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    if url:
+        await _run("open", url)
+
+    proc = await asyncio.create_subprocess_exec(
+        _BINARY, "diff", "screenshot",
+        "--baseline", str(base),
+        "-o", str(out),
+        "-t", str(threshold),
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    try:
+        raw_out, raw_err = await asyncio.wait_for(
+            proc.communicate(), timeout=_CMD_TIMEOUT_S
+        )
+    except asyncio.TimeoutError as exc:  # pragma: no cover - defensive
+        proc.kill()
+        raise BrowserError(f"`{_BINARY} diff screenshot` timed out") from exc
+
+    text = (raw_out.decode(errors="replace") + "\n" + raw_err.decode(errors="replace")).strip()
+    dim_mismatch = "dimension mismatch" in text.lower()
+    pct = None
+    px = None
+    if not dim_mismatch:
+        m = _PCT_RE.search(text)
+        if m:
+            pct = float(m.group(1))
+        m = _PIXELS_RE.search(text)
+        if m:
+            px = int(m.group(1).replace(",", ""))
+    return DiffResult(
+        mismatch_pct=pct,
+        diff_pixels=px,
+        diff_image=str(out) if out.exists() else None,
+        dimension_mismatch=dim_mismatch,
+        raw=text,
+    )
+
+
+async def close() -> None:
+    """Close the active browser session (best-effort)."""
+    try:
+        await _run("close")
+    except BrowserError:
+        pass

devops_bot_sdk-1.4.101/sdk/design_verify/compare.py

@@ -0,0 +1,150 @@
+"""Vision comparison of a rendered UI against the original design.
+
+Instead of adding an `anthropic`/`openai` dependency, this reuses the local
+``claude`` CLI (via :func:`sdk.local_exec.run_claude_local`). The CLI's built-in
+``Read`` tool reads image files natively, so we point it at BOTH the original
+design screenshot and the freshly rendered one and ask it to produce a strict
+JSON diff. This keeps the loop dependency-free and consistent with how the rest
+of the SDK already shells out to the local agent.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from sdk.local_exec import run_claude_local
+
+# Only Read is needed — the comparison must never edit files.
+_COMPARE_TOOLS = ["Read"]
+
+
+@dataclass
+class Discrepancy:
+    area: str            # e.g. "header", "primary CTA", "card grid spacing"
+    severity: str        # "high" | "medium" | "low"
+    expected: str        # what the design shows
+    actual: str          # what the rendered UI shows
+
+
+@dataclass
+class ComparisonReport:
+    fidelity_score: int                       # 0-100, higher = closer to design
+    discrepancies: list[Discrepancy] = field(default_factory=list)
+    correction_prompt: str = ""               # concrete fix instructions for the coder
+    raw: str = ""                             # raw model output (for debugging)
+
+    @property
+    def passed(self) -> bool:
+        return self.fidelity_score >= 0  # threshold applied by the loop, not here
+
+
+def _build_compare_prompt(
+    design_path: Path,
+    rendered_path: Path,
+    diff_path: Path | None = None,
+    diff_note: str = "",
+) -> str:
+    """Prompt the local agent to diff two images and emit strict JSON only."""
+    diff_block = ""
+    if diff_path is not None:
+        diff_block = (
+            f"  3. PIXEL DIFF (changed regions highlighted in red): {diff_path}\n"
+        )
+    hint = ""
+    if diff_note:
+        hint = (
+            "\nA pixel-level comparison was already run: "
+            f"{diff_note} Read the PIXEL DIFF image to see WHERE the pixels "
+            "differ (red = changed), and use it to localize your review — but "
+            "judge semantically, not by raw pixel count (fonts/anti-aliasing/"
+            "placeholder content inflate raw pixel diffs).\n"
+        )
+    return (
+        "You are a meticulous UI design reviewer. Images are on disk:\n"
+        f"  1. TARGET DESIGN (the intended look): {design_path}\n"
+        f"  2. CURRENT RENDER (what our generated frontend actually looks like): "
+        f"{rendered_path}\n"
+        f"{diff_block}"
+        f"{hint}\n"
+        "Use the Read tool to open and view the images. Then compare the CURRENT "
+        "RENDER against the TARGET DESIGN across: overall layout & structure, "
+        "spacing/alignment, colors, typography (family/size/weight), component "
+        "presence and ordering, iconography, and content/labels.\n\n"
+        "Output ONLY a single JSON object (no prose, no markdown fences) with this "
+        "exact shape:\n"
+        "{\n"
+        '  "fidelity_score": <int 0-100, how closely the render matches the design>,\n'
+        '  "discrepancies": [\n'
+        '    {"area": "<region/component>", "severity": "high|medium|low", '
+        '"expected": "<what the design shows>", "actual": "<what the render shows>"}\n'
+        "  ],\n"
+        '  "correction_prompt": "<a concise, imperative set of concrete code changes '
+        "that would close the gaps — reference components, colors (hex if visible), "
+        'spacing, and layout explicitly so a coding agent can act on it directly>"\n'
+        "}\n\n"
+        "Rank discrepancies most-severe first. If the render already matches "
+        "closely, return a high score, an empty discrepancies list, and an empty "
+        "correction_prompt."
+    )
+
+
+def _extract_json(text: str) -> dict:
+    """Pull the first balanced JSON object out of the model's output."""
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1 or end <= start:
+        raise ValueError(f"no JSON object found in comparison output: {text[:200]!r}")
+    return json.loads(text[start : end + 1])
+
+
+async def compare_design(
+    design_path: str | Path,
+    rendered_path: str | Path,
+    *,
+    work_dir: str | Path,
+    diff_path: str | Path | None = None,
+    diff_note: str = "",
+) -> ComparisonReport:
+    """Diff a rendered screenshot against the target design; return a report.
+
+    ``work_dir`` is the cwd handed to the local ``claude`` CLI — any readable dir
+    works; the image paths are passed absolute so location does not matter.
+
+    ``diff_path``/``diff_note`` optionally pass a pre-computed pixel-diff image
+    (from :func:`sdk.design_verify.browser.diff_baseline`) and its metrics, so
+    the vision model can localize its review to the highlighted regions.
+    """
+    design = Path(design_path).expanduser().resolve()
+    rendered = Path(rendered_path).expanduser().resolve()
+    for p in (design, rendered):
+        if not p.exists():
+            raise FileNotFoundError(f"image not found: {p}")
+    diff = Path(diff_path).expanduser().resolve() if diff_path else None
+    if diff is not None and not diff.exists():
+        diff = None  # diff is a best-effort aid; never fail the review on it
+
+    result = await run_claude_local(
+        _build_compare_prompt(design, rendered, diff, diff_note),
+        str(work_dir),
+        allowed_tools=_COMPARE_TOOLS,
+    )
+    if not result.get("ok"):
+        raise RuntimeError(f"comparison run failed: {result.get('error')}")
+
+    raw = result.get("result", "") or ""
+    data = _extract_json(raw)
+    return ComparisonReport(
+        fidelity_score=int(data.get("fidelity_score", 0)),
+        discrepancies=[
+            Discrepancy(
+                area=str(d.get("area", "")),
+                severity=str(d.get("severity", "")),
+                expected=str(d.get("expected", "")),
+                actual=str(d.get("actual", "")),
+            )
+            for d in data.get("discrepancies", [])
+        ],
+        correction_prompt=str(data.get("correction_prompt", "")),
+        raw=raw,
+    )

devops_bot_sdk-1.4.101/sdk/design_verify/loop.py

@@ -0,0 +1,204 @@
+"""The closed refinement loop: render -> compare -> correct -> repeat.
+
+This is the piece that turns a one-shot design-to-code generation into a
+self-correcting one. It assumes the frontend has already been generated once and
+is being served at ``preview_url`` (a local dev server). Each iteration:
+
+    1. screenshot the live preview with agent-browser
+    2. compare it against the target design (local claude vision diff)
+    3. stop if fidelity >= threshold or we've run out of iterations
+    4. otherwise feed the correction prompt back to the coding agent, which edits
+       the real files; then loop (the caller's dev server hot-reloads)
+
+The coding step is injectable (``coder``) so the real pipeline can plug in its
+session-resuming ``run_claude_local`` call (keeping context across iterations)
+instead of the default fresh-run coder used here.
+"""
+from __future__ import annotations
+
+import asyncio
+import shutil
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from sdk.local_exec import DEFAULT_ALLOWED_TOOLS, run_claude_local
+
+from .bootstrap import ensure_agent_browser
+from .browser import BrowserError, diff_baseline, render_screenshot
+from .compare import ComparisonReport, compare_design
+
+# A coder takes (project_path, correction_prompt) and applies fixes in place.
+Coder = Callable[[str, str], Awaitable[None]]
+
+
+@dataclass
+class Iteration:
+    index: int
+    screenshot: str
+    fidelity_score: int
+    discrepancy_count: int
+
+
+@dataclass
+class RefinementResult:
+    passed: bool
+    iterations: list[Iteration] = field(default_factory=list)
+    final_report: ComparisonReport | None = None
+
+    @property
+    def best_score(self) -> int:
+        return max((it.fidelity_score for it in self.iterations), default=0)
+
+
+async def _default_coder(project_path: str, correction_prompt: str) -> None:
+    """Fallback coder: a fresh local `claude` run that applies the corrections.
+
+    The real pipeline should pass a ``coder`` that RESUMES the ticket's session
+    (``resume_session_id=...``) so the agent keeps the design context across
+    iterations instead of starting cold each time.
+    """
+    prompt = (
+        "A visual review compared the current frontend against the target design "
+        "and found the differences below. Edit the code in this repository to "
+        "close them. Make the minimal, correct changes; do not restructure "
+        "unrelated code.\n\n"
+        f"{correction_prompt}"
+    )
+    result = await run_claude_local(
+        prompt, project_path, allowed_tools=DEFAULT_ALLOWED_TOOLS
+    )
+    if not result.get("ok"):
+        raise RuntimeError(f"correction run failed: {result.get('error')}")
+
+
+async def verify_and_refine(
+    *,
+    project_path: str | Path,
+    design_path: str | Path,
+    preview_url: str,
+    artifact_dir: str | Path | None = None,
+    cleanup: bool = True,
+    threshold: int = 90,
+    max_iterations: int = 3,
+    full_page: bool = False,
+    coder: Coder | None = None,
+    on_event: Callable[[str], None] | None = None,
+) -> RefinementResult:
+    """Iteratively refine the generated UI until it matches ``design_path``.
+
+    Args:
+        project_path: repo whose frontend files get edited on each correction.
+        design_path:  the original design image (e.g. the JIRA screenshot).
+        preview_url:  URL where the generated UI is being served (dev server).
+        artifact_dir: scratch dir for per-iteration screenshots. **Optional** — if
+                      omitted, an OS temp dir is created and (by default) deleted
+                      when the run ends. Screenshots are working artifacts, NOT
+                      permanent storage.
+        cleanup:      delete the screenshots/diffs when the run ends (default
+                      True). Set False only for debugging. Note: when True, the
+                      screenshot paths in the returned result no longer exist.
+        threshold:    stop once fidelity_score >= this (0-100).
+        max_iterations: hard cap on correction rounds.
+        coder:        applies corrections; defaults to a fresh local claude run.
+        on_event:     optional progress sink (receives human-readable lines).
+
+    Returns a :class:`RefinementResult` with per-iteration scores and the final
+    comparison report.
+    """
+    project_path = str(project_path)
+    # Screenshots are ephemeral working files. Default to a private OS temp dir
+    # that we remove in the `finally` below — nothing is persisted unless the
+    # caller both passes an artifact_dir AND sets cleanup=False.
+    if artifact_dir is None:
+        art = Path(tempfile.mkdtemp(prefix="agentos_design_verify_"))
+    else:
+        art = Path(artifact_dir).expanduser().resolve()
+        art.mkdir(parents=True, exist_ok=True)
+    coder = coder or _default_coder
+
+    def emit(msg: str) -> None:
+        if on_event:
+            on_event(msg)
+
+    result = RefinementResult(passed=False)
+    report: ComparisonReport | None = None
+
+    # try/finally spans everything after the scratch dir exists, so the dir is
+    # always removed — even if bootstrap or the first render raises.
+    try:
+        # Provision agent-browser for THIS user on first use (idempotent, cached).
+        # The loop can't render without it, so this is a hard prerequisite — but
+        # the bootstrap never raises; we surface a clear, actionable error.
+        emit("ensuring agent-browser is installed")
+        boot = await asyncio.to_thread(ensure_agent_browser)
+        if not boot.ok:
+            raise BrowserError(f"agent-browser unavailable: {boot.reason}")
+        if boot.installed:
+            emit(f"agent-browser provisioned: {boot.reason}")
+
+        for i in range(1, max_iterations + 1):
+            shot = art / f"render_iter_{i}.png"
+            emit(f"[iter {i}/{max_iterations}] rendering {preview_url}")
+            await render_screenshot(preview_url, shot, full_page=full_page)
+
+            # Native pixel diff first — a fast, localizing signal + a highlight
+            # image the vision step can reason over. Best-effort: design mocks
+            # often differ in dimensions (CLI refuses the pixel compare), so never
+            # fail the loop on it — fall back to a pure vision comparison.
+            diff_path: str | None = None
+            diff_note = ""
+            try:
+                dr = await diff_baseline(
+                    design_path, out_path=art / f"diff_iter_{i}.png"
+                )
+                if dr.dimension_mismatch:
+                    diff_note = (
+                        "the render and design differ in dimensions, so no pixel "
+                        "diff was produced."
+                    )
+                elif dr.mismatch_pct is not None:
+                    diff_path = dr.diff_image
+                    diff_note = f"the raw pixel mismatch is {dr.mismatch_pct:.1f}%."
+            except BrowserError as exc:
+                emit(f"[iter {i}/{max_iterations}] pixel diff skipped: {exc}")
+
+            emit(f"[iter {i}/{max_iterations}] comparing against design")
+            report = await compare_design(
+                design_path, shot, work_dir=art,
+                diff_path=diff_path, diff_note=diff_note,
+            )
+            result.iterations.append(
+                Iteration(
+                    index=i,
+                    screenshot=str(shot),
+                    fidelity_score=report.fidelity_score,
+                    discrepancy_count=len(report.discrepancies),
+                )
+            )
+            emit(
+                f"[iter {i}/{max_iterations}] fidelity={report.fidelity_score} "
+                f"discrepancies={len(report.discrepancies)}"
+            )
+
+            if report.fidelity_score >= threshold or not report.correction_prompt:
+                result.passed = report.fidelity_score >= threshold
+                break
+
+            if i == max_iterations:
+                break  # scored but out of correction budget
+
+            emit(f"[iter {i}/{max_iterations}] applying corrections")
+            await coder(project_path, report.correction_prompt)
+            # Give a hot-reloading dev server a moment to rebuild before re-shooting.
+            time.sleep(2)
+    finally:
+        # Screenshots/diffs are working artifacts, never permanent storage.
+        if cleanup:
+            shutil.rmtree(art, ignore_errors=True)
+            emit("cleaned up screenshots")
+
+    result.final_report = report
+    return result

{devops_bot_sdk-1.4.96 → devops_bot_sdk-1.4.101}/sdk/ipc/handlers.py

@@ -162,6 +162,7 @@ def _build_local_prompt(
     repo_name: str | None = None,
     grounded: bool = False,
     branch_convention: str | None = None,
+    design_image_path: str | None = None,
 ) -> str:
     """Compose the coding prompt for the local claude CLI from the server plan.
 
@@ -200,6 +201,21 @@ def _build_local_prompt(
                 "code actually is, trust the code and the operator instructions."
             )
         parts.append(scope_line)
+    # 0.5 Design reference — when the Jira ticket has a design screenshot it is the
+    #     authoritative VISUAL spec. Placed near the top so the model attends to it;
+    #     the local claude agent's Read tool views images natively, so it can code
+    #     against the real design instead of blind from the text description.
+    if design_image_path:
+        parts.append(
+            "=== Design reference (AUTHORITATIVE visual spec) ===\n"
+            f"A design screenshot for this task is attached at: {design_image_path}\n"
+            "Use the Read tool to VIEW this image BEFORE writing any UI code, and "
+            "match it precisely: layout & structure, spacing & alignment, colors, "
+            "typography (family/size/weight), component choices, and iconography. "
+            "When the image and the text description conflict, the image wins for "
+            "anything visual. Treat visual fidelity to this design as a required "
+            "acceptance criterion."
+        )
     # 1. Operator instructions — FIRST, verbatim, authoritative.
     if human_instructions and human_instructions.strip():
         parts.append(
@@ -1648,6 +1664,35 @@ def _tool_detail(tool_name: str, inp: dict) -> str:
     return ""
 
 
+async def _download_design_image(client: "BackendClient", task_id: str) -> str | None:
+    """Best-effort: download the ticket's design screenshot to a temp file.
+
+    The local claude agent Reads this path to code against the real design (not
+    blind from text). Returns the temp path or None (no image / any failure).
+    EPHEMERAL — the caller MUST delete it after the run; it is never persisted.
+    """
+    if not task_id:
+        return None
+    try:
+        img = await client.fetch_design_image(task_id)
+    except Exception:  # noqa: BLE001 — visual grounding is best-effort
+        return None
+    if not img:
+        return None
+    data, mime = img
+    m = (mime or "").lower()
+    ext = ".png" if "png" in m else (".jpg" if ("jpeg" in m or "jpg" in m) else ".img")
+    try:
+        import os
+        import tempfile
+        fd, path = tempfile.mkstemp(prefix="agentos_design_", suffix=ext)
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        return path
+    except OSError:
+        return None
+
+
 async def _code_one_repo(
     client: BackendClient,
     *,
@@ -1874,21 +1919,36 @@ async def _code_one_repo(
     # When recon ran, the implementation resumes that session so its grounded plan
     # (and the technical PRD, if generated) stays in context; if a PRD is present the
     # prompt makes it the authoritative spec.
+    # Design-aware generation: if the ticket has a design screenshot, download it
+    # (ephemeral) so the local agent can Read it while coding. Consumed by the
+    # FIRST run below — after that it's in the session context, so recovery/repair
+    # resumes don't need the file. Deleted in `finally` regardless of outcome.
+    design_path = await _download_design_image(client, task_id)
+
     prompt = _build_local_prompt(
         pending["user_input"], pending.get("structured_plan"),
         pending.get("human_instructions"),
         agent_mode=agent_mode, git_managed=bool(branch_info),
         repo_name=name, grounded=bool(recon_session), branch_convention=branch_name,
+        design_image_path=design_path,
     )
 
     # 3b. initial claude run. resume_session_id (rate-limit/context retry) wins;
     # otherwise resume the recon session so implementation builds on the recon
     # exploration instead of starting cold.
-    result = await local_exec.run_claude_local(
-        prompt, repo_path, on_event=_on_event,
-        github_token=gh_token, approval_dir=approval_dir,
-        resume_session_id=resume_session_id or recon_session or None,
-    )
+    try:
+        result = await local_exec.run_claude_local(
+            prompt, repo_path, on_event=_on_event,
+            github_token=gh_token, approval_dir=approval_dir,
+            resume_session_id=resume_session_id or recon_session or None,
+        )
+    finally:
+        if design_path:
+            import os
+            try:
+                os.remove(design_path)
+            except OSError:
+                pass
 
     # 4. context-window recovery
     import time as _time