patchr 0.1.0__py3-none-any.whl

picux/tools/shared.py

@@ -0,0 +1,2048 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import html
+import ipaddress
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote_plus, urlencode, unquote_to_bytes, urlparse
+from urllib.request import Request, urlopen
+
+from picux.core import PicuxIntentRouter
+
+
+SHARED_DOMAINS = {"hunt", "bridge", "resolve", "proxy", "pay"}
+DEFAULT_FX_RATES = {
+    "USD": 1.0,
+    "SEK": 9.207515,
+    "NGN": 1359.86,
+}
+
+
+@dataclass(frozen=True)
+class NLPTool:
+    """Classify raw user input and detect follow-up context for domain routing."""
+
+    router: PicuxIntentRouter = field(default_factory=PicuxIntentRouter)
+
+    def run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        query = _query(payload)
+        context = payload.get("context", {}) if isinstance(payload.get("context"), dict) else {}
+        taskId = str(payload.get("taskId", context.get("taskId", "")) or "")
+        decision = self.router.classify(query)
+        route = _route(query, seed=decision.domain.value)
+        entities = _entities(query, payload)
+        isFollowUp = bool(taskId and _looksLikeFollowUp(query))
+        return {
+            "ok": True,
+            "tool": "nlpTool",
+            "input": query,
+            "intent": {
+                "domain": route[0] if route else decision.domain.value,
+                "reason": decision.reason,
+                "kind": _intentKind(query),
+            },
+            "route": route,
+            "isFollowUp": isFollowUp,
+            "followUp": {
+                "taskId": taskId,
+                "state": str(context.get("state", context.get("status", "")) or ""),
+                "reason": "ongoingTaskReference" if isFollowUp else "",
+            },
+            "entities": entities,
+            "confidence": _confidence(query, route, entities),
+        }
+
+
+@dataclass(frozen=True)
+class ImageReader:
+    """Read image evidence and return query-relevant text signals."""
+
+    def read(self, payload: dict[str, Any]) -> dict[str, Any]:
+        query = _query(payload)
+        images = _imageInputs(payload)
+        readings = []
+        evidence = []
+        for index, image in enumerate(images, start=1):
+            rawBytes = _imageBytes(image)
+            text = _imageText(image, rawBytes)
+            digest = hashlib.sha256(rawBytes or text.encode("utf-8")).hexdigest() if rawBytes or text else ""
+            matches = _matches(query, text)
+            imageId = str(image.get("imageId", image.get("artifactId", image.get("name", f"image_{index}"))) or f"image_{index}")
+            reading = {
+                "imageId": imageId,
+                "name": str(image.get("name", imageId) or imageId),
+                "mime": str(image.get("mime", image.get("contentType", "")) or ""),
+                "sha256": digest,
+                "text": _redact(text[:4000]),
+                "matches": matches,
+                "summary": _summary(text, matches),
+                "sourceBound": bool(digest),
+            }
+            readings.append(reading)
+            evidence.append(
+                {
+                    "kind": "imageText",
+                    "name": reading["name"],
+                    "sha256": digest,
+                    "mime": reading["mime"],
+                    "label": f"image:{reading['name']}",
+                    "source": "picux://tools/imageReader",
+                    "summary": reading["summary"],
+                }
+            )
+        return {
+            "ok": True,
+            "tool": "imageReader",
+            "query": query,
+            "count": len(readings),
+            "readings": readings,
+            "evidence": evidence,
+            "status": "read" if readings else "noImages",
+        }
+
+
+@dataclass(frozen=True)
+class BrowserReader:
+    """Headless-browser compatible website reader with a safe stdlib fallback."""
+
+    timeoutSec: int = 6
+    renderedTimeoutMs: int = 12000
+    renderedCommand: tuple[str, ...] | None = None
+
+    def read(self, payload: dict[str, Any]) -> dict[str, Any]:
+        query = _query(payload)
+        payloadEntities = payload.get("entities", {}) if isinstance(payload.get("entities"), dict) else {}
+        entities = {**payloadEntities, **_entities(query, payload)}
+        fxRates = _fxRates(payload)
+        budget = _budgetContext(query, payload, fxRates)
+        urls = [str(item).strip() for item in payload.get("urls", []) if str(item).strip()] if isinstance(payload.get("urls"), list) else []
+        marketplaceSet = _marketplaceSet(query, entities, payload)
+        searchTargets = _searchTargets(query, entities, payload, marketplaceSet=marketplaceSet)
+        allowNetwork = bool(payload.get("allowNetwork", payload.get("live", False)))
+        suppliedTargets = [{"source": "clientUrl", "url": url, "kind": "supplied"} for url in urls]
+        liveTargets = searchTargets if allowNetwork else []
+        readTargets = _dedupeTargets([*suppliedTargets, *liveTargets])
+        allowPrivateNetwork = bool(payload.get("allowPrivateNetwork", payload.get("allowLocalNetwork", False)))
+        preferRendered = allowNetwork and str(payload.get("browserMode", payload.get("adapter", "auto")) or "auto").lower() not in {"http", "stdlib", "stdlibhttpreader"}
+        searchText = str(payload.get("searchText", entities.get("item", "") or query) or "").strip()
+        targetLimit = _targetLimit(payload)
+        selectedTargets = readTargets[:targetLimit]
+        blockedTargets = [
+            _blockedUrlObservation(
+                str(target.get("url", "") or ""),
+                query,
+                source=str(target.get("source", "source") or "source"),
+                error=blockedReason,
+            )
+            for target in selectedTargets
+            for blockedReason in [_privateTargetBlockReason(str(target.get("url", "") or ""), allowPrivateNetwork=allowPrivateNetwork)]
+            if blockedReason
+        ]
+        safeTargets = [
+            target
+            for target in selectedTargets
+            if not _privateTargetBlockReason(str(target.get("url", "") or ""), allowPrivateNetwork=allowPrivateNetwork)
+        ]
+        rendered = self._readRendered(safeTargets, query, searchText) if preferRendered and safeTargets else _renderedSkipped("notRequested" if safeTargets else "noTargets")
+        observations = [*blockedTargets, *rendered["observations"]]
+        adapter = "playwrightChromium" if observations and rendered["meta"].get("available") else "stdlibHttpReader"
+        if not rendered["observations"]:
+            observations = list(blockedTargets)
+            for target in safeTargets:
+                observations.append(self._readUrl(str(target.get("url", "")), query, source=str(target.get("source", "source") or "source"), allowPrivateNetwork=allowPrivateNetwork))
+            adapter = "stdlibHttpReader"
+        offers = _offersFromObservations(observations, query, entities, budget=budget, fxRates=fxRates)
+        errors = [item for item in observations if not item.get("ok")]
+        if observations and len(errors) == len(observations):
+            status = "ioError"
+        elif observations:
+            status = "read"
+        elif searchTargets:
+            status = "needsSourceUrls"
+        else:
+            status = "noSources"
+        return {
+            "ok": not observations or len(errors) < len(observations),
+            "tool": "browserReader",
+            "engine": "renderedBrowserCompatible",
+            "adapter": adapter,
+            "rendered": rendered["meta"],
+            "query": query,
+            "marketplaceSet": marketplaceSet,
+            "budget": budget,
+            "fx": {"base": "USD", "rates": fxRates, "mode": "fallbackOrOverride"},
+            "searchTargets": searchTargets,
+            "observations": observations,
+            "offers": offers,
+            "errors": errors,
+            "marketplaceAttempts": _attemptSummaries(observations),
+            "networkAttempted": allowNetwork,
+            "status": status,
+        }
+
+    def _readUrl(self, url: str, query: str, *, source: str = "source", allowPrivateNetwork: bool = False) -> dict[str, Any]:
+        parsed = urlparse(url)
+        if parsed.scheme == "data":
+            raw = unquote_to_bytes(parsed.path.split(",", 1)[1] if "," in parsed.path else parsed.path)
+            text = raw.decode("utf-8", errors="ignore")
+            return _pageObservation(url, text, query, "dataUrl", source=source, statusCode=200)
+        if parsed.scheme not in {"http", "https"}:
+            return {"source": source, "url": url, "ok": False, "adapter": "http", "error": "unsupportedScheme", "snippets": []}
+        blockedReason = _privateTargetBlockReason(url, allowPrivateNetwork=allowPrivateNetwork)
+        if blockedReason:
+            return _blockedUrlObservation(url, query, source=source, error=blockedReason)
+        try:
+            request = Request(
+                url,
+                headers={
+                    "User-Agent": "Mozilla/5.0 (compatible; PicuxBrowserReader/0.1; +https://picux.ai)",
+                    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                    "Accept-Language": "en-US,en;q=0.9,sv;q=0.7",
+                },
+            )
+            with urlopen(request, timeout=self.timeoutSec) as response:
+                raw = response.read(500_000)
+                statusCode = int(getattr(response, "status", 200) or 200)
+            text = raw.decode("utf-8", errors="ignore")
+            return _pageObservation(url, text, query, "http", source=source, statusCode=statusCode)
+        except Exception as exc:
+            return {"source": source, "url": url, "ok": False, "adapter": "http", "statusCode": int(getattr(exc, "code", 0) or 0), "error": str(exc)[:180], "snippets": []}
+
+    def _readRendered(self, targets: list[dict[str, str]], query: str, searchText: str) -> dict[str, Any]:
+        command = self._renderedCommand()
+        if not command:
+            return _renderedSkipped("missingRenderedCommand")
+        payload = {
+            "query": query,
+            "searchText": searchText,
+            "targets": targets,
+            "timeoutMs": self.renderedTimeoutMs,
+        }
+        try:
+            completed = subprocess.run(
+                list(command),
+                input=json.dumps(payload, ensure_ascii=True),
+                capture_output=True,
+                check=False,
+                text=True,
+                timeout=max(10, int((self.renderedTimeoutMs / 1000) * max(1, len(targets)) + 8)),
+            )
+        except Exception as exc:
+            return _renderedSkipped("renderedCommandFailed", str(exc)[:220])
+        if completed.returncode != 0:
+            return _renderedSkipped("renderedCommandNonZero", (completed.stderr or completed.stdout)[:220])
+        try:
+            result = json.loads(completed.stdout or "{}")
+        except Exception as exc:
+            return _renderedSkipped("renderedCommandInvalidJson", str(exc)[:220])
+        meta = result.get("meta") if isinstance(result.get("meta"), dict) else {}
+        observations = _normalizeRenderedObservations(result.get("observations", []), query)
+        renderedMeta = {
+            "attempted": bool(meta.get("attempted", True)),
+            "available": bool(meta.get("available", bool(observations))),
+            "status": str(meta.get("status", "rendered" if observations else "unavailable") or ""),
+            "fallbackReason": str(meta.get("fallbackReason", "") or ""),
+            "adapter": str(result.get("adapter", "playwrightChromium") or "playwrightChromium"),
+        }
+        if meta.get("error"):
+            renderedMeta["error"] = str(meta.get("error", "") or "")[:220]
+        for key in ("browserProvider", "executablePath", "fallbackReasonDetail"):
+            if meta.get(key):
+                renderedMeta[key] = str(meta.get(key, "") or "")[:600]
+        return {
+            "observations": observations,
+            "meta": renderedMeta,
+        }
+
+    def _renderedCommand(self) -> tuple[str, ...]:
+        if self.renderedCommand:
+            return self.renderedCommand
+        script = Path(__file__).resolve().parents[3] / "scripts" / "picux-rendered-browser.mjs"
+        return ("node", str(script)) if script.exists() else ()
+
+
+@dataclass(frozen=True)
+class BrowserCheckout:
+    """Source-bound browser checkout attempt that fails closed when purchase execution is not proven."""
+
+    renderedTimeoutMs: int = 20000
+    renderedCommand: tuple[str, ...] | None = None
+
+    def run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        url = str(payload.get("url", payload.get("sourceUrl", "")) or "").strip()
+        candidateId = str(payload.get("candidateId", payload.get("sourceId", "")) or "")
+        source = str(payload.get("source", "") or "")
+        execute = bool(payload.get("executePurchase", payload.get("allowPurchaseExecution", False)))
+        if not url:
+            return self._blocked("missingListingUrl", url=url, candidateId=candidateId, source=source, execute=execute)
+        parsed = urlparse(url)
+        if not execute:
+            return self._blocked("purchaseExecutionNotAuthorized", url=url, candidateId=candidateId, source=source, execute=execute)
+        if parsed.scheme in {"file", "about", "javascript"}:
+            return self._blocked("unsupportedCheckoutUrlScheme", url=url, candidateId=candidateId, source=source, execute=execute)
+        blockedReason = _privateTargetBlockReason(url, allowPrivateNetwork=bool(payload.get("allowPrivateNetwork", payload.get("allowLocalNetwork", False))))
+        if blockedReason:
+            return self._blocked(blockedReason, url=url, candidateId=candidateId, source=source, execute=execute)
+        if parsed.scheme == "data":
+            return self._dataCheckout(url, candidateId=candidateId, source=source, execute=execute)
+        rendered = self._runRendered(payload, url=url, candidateId=candidateId, source=source, execute=execute)
+        if rendered:
+            return rendered
+        return self._blocked("marketplaceCheckoutAdapterMissing", url=url, candidateId=candidateId, source=source, execute=execute)
+
+    def _dataCheckout(self, url: str, *, candidateId: str, source: str, execute: bool) -> dict[str, Any]:
+        try:
+            raw = unquote_to_bytes(urlparse(url).path.split(",", 1)[1] if "," in urlparse(url).path else urlparse(url).path)
+            text = raw.decode("utf-8", errors="ignore")
+        except Exception as exc:
+            return self._blocked(f"dataCheckoutReadFailed:{str(exc)[:80]}", url=url, candidateId=candidateId, source=source, execute=execute)
+        lowered = text.lower()
+        if "data-picux-checkout=\"success\"" in lowered or "data-picux-checkout='success'" in lowered or "purchase complete" in lowered or "order confirmed" in lowered:
+            receiptId = _stableToolId("purchase", {"url": url, "candidateId": candidateId, "source": source})
+            return {
+                "ok": True,
+                "tool": "browserCheckout",
+                "status": "purchased",
+                "reason": "",
+                "message": "Item successfully purchased",
+                "candidateId": candidateId,
+                "source": source,
+                "url": url,
+                "executePurchase": execute,
+                "receipt": {"receiptId": receiptId, "status": "confirmed", "source": source, "candidateId": candidateId, "url": url},
+            }
+        if "out of stock" in lowered or "sold out" in lowered:
+            return self._blocked("itemUnavailable", url=url, candidateId=candidateId, source=source, execute=execute)
+        if "payment declined" in lowered or "payment failed" in lowered:
+            return self._blocked("paymentDeclined", url=url, candidateId=candidateId, source=source, execute=execute)
+        if "mfa required" in lowered or "verification code" in lowered or "one-time code" in lowered:
+            blocked = self._blocked("mfaRequired", url=url, candidateId=candidateId, source=source, execute=execute)
+            return {**blocked, "status": "needsInput", "needsInput": [{"key": "mfaCode", "label": "MFA code", "secret": True}]}
+        if "login required" in lowered or "sign in" in lowered or "account required" in lowered:
+            blocked = self._blocked("loginOrAccountRequired", url=url, candidateId=candidateId, source=source, execute=execute)
+            return {**blocked, "status": "needsInput", "needsInput": [{"key": "portalSessionId", "label": "Authenticated marketplace session", "secret": False}]}
+        return self._blocked("purchaseConfirmationNotFound", url=url, candidateId=candidateId, source=source, execute=execute)
+
+    def _runRendered(self, payload: dict[str, Any], *, url: str, candidateId: str, source: str, execute: bool) -> dict[str, Any]:
+        command = self._renderedCommand()
+        if not command:
+            return {}
+        try:
+            completed = subprocess.run(
+                list(command),
+                input=json.dumps({**payload, "url": url, "candidateId": candidateId, "source": source, "executePurchase": execute, "timeoutMs": self.renderedTimeoutMs}, ensure_ascii=True),
+                capture_output=True,
+                check=False,
+                text=True,
+                timeout=max(12, int(self.renderedTimeoutMs / 1000) + 10),
+            )
+        except Exception as exc:
+            return self._blocked(f"browserCheckoutCommandFailed:{str(exc)[:120]}", url=url, candidateId=candidateId, source=source, execute=execute)
+        if completed.returncode != 0:
+            return self._blocked(f"browserCheckoutCommandNonZero:{(completed.stderr or completed.stdout)[:120]}", url=url, candidateId=candidateId, source=source, execute=execute)
+        try:
+            result = json.loads(completed.stdout or "{}")
+        except Exception as exc:
+            return self._blocked(f"browserCheckoutInvalidJson:{str(exc)[:120]}", url=url, candidateId=candidateId, source=source, execute=execute)
+        if not isinstance(result, dict):
+            return self._blocked("browserCheckoutInvalidResult", url=url, candidateId=candidateId, source=source, execute=execute)
+        return {
+            "tool": "browserCheckout",
+            "candidateId": candidateId,
+            "source": source,
+            "url": url,
+            "executePurchase": execute,
+            **result,
+        }
+
+    def _renderedCommand(self) -> tuple[str, ...]:
+        if self.renderedCommand:
+            return self.renderedCommand
+        script = Path(__file__).resolve().parents[3] / "scripts" / "picux-rendered-checkout.mjs"
+        return ("node", str(script)) if script.exists() else ()
+
+    @staticmethod
+    def _blocked(reason: str, *, url: str, candidateId: str, source: str, execute: bool) -> dict[str, Any]:
+        return {
+            "ok": False,
+            "tool": "browserCheckout",
+            "status": "blocked",
+            "reason": reason,
+            "message": f"Sorry, I am unable to make the purchase due to {reason}.",
+            "candidateId": candidateId,
+            "source": source,
+            "url": url,
+            "executePurchase": execute,
+        }
+
+
+@dataclass(frozen=True)
+class PortalBrowser:
+    """Authenticated portal action runner that fails closed and returns proof-ready artifacts."""
+
+    timeoutSec: int = 8
+    renderedTimeoutMs: int = 20000
+    renderedCommand: tuple[str, ...] | None = None
+
+    def run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        targetUrl = str(payload.get("targetUrl", payload.get("url", "")) or "").strip()
+        actionId = str(payload.get("portalActionId", payload.get("actionId", "")) or "")
+        session = payload.get("session", {}) if isinstance(payload.get("session"), dict) else {}
+        credentialRef = str(payload.get("credentialRef", session.get("credentialRef", "")) or "")
+        storageStateRef = str(payload.get("storageStateRef", session.get("storageStateRef", "")) or "")
+        steps = _portalStepResults(payload.get("steps", []))
+        inputs = payload.get("inputs", {}) if isinstance(payload.get("inputs"), dict) else {}
+        if not targetUrl:
+            return {**self._blocked("missingTargetUrl", actionId=actionId, targetUrl=targetUrl), "steps": _portalStepsWithStatus(steps, "blocked", reason="missingTargetUrl")}
+        scheme = urlparse(targetUrl).scheme
+        if scheme in {"file", "about", "javascript"}:
+            return {**self._blocked("unsupportedPortalTargetScheme", actionId=actionId, targetUrl=targetUrl), "steps": _portalStepsWithStatus(steps, "blocked", reason="unsupportedPortalTargetScheme")}
+        blockedReason = _privateTargetBlockReason(targetUrl, allowPrivateNetwork=bool(payload.get("allowPrivateNetwork", payload.get("allowLocalNetwork", False))))
+        if blockedReason:
+            return {**self._blocked(blockedReason, actionId=actionId, targetUrl=targetUrl), "steps": _portalStepsWithStatus(steps, "blocked", reason=blockedReason)}
+        if not credentialRef and not storageStateRef and not targetUrl.startswith("data:"):
+            return {
+                **self._blocked("authRequired", actionId=actionId, targetUrl=targetUrl),
+                "status": "needsInput",
+                "needsInput": [{"key": "credentialRef", "label": "Credential reference", "secret": True}],
+                "steps": _portalStepsWithStatus(steps, "pending", reason="authRequired"),
+            }
+        missingInputs = _missingPortalInputs(steps, inputs, requiredKeys=_portalRequiredInputs(payload, steps))
+        if missingInputs:
+            return {
+                **self._blocked("missingPortalInputs", actionId=actionId, targetUrl=targetUrl),
+                "status": "needsInput",
+                "needsInput": missingInputs,
+                "steps": _portalStepsWithMissingInputs(steps, missingInputs),
+            }
+        allowNetwork = bool(payload.get("allowNetwork", payload.get("live", payload.get("executePortal", False))))
+        rendered = self._runRendered(payload, targetUrl=targetUrl, actionId=actionId, steps=steps, allowNetwork=allowNetwork)
+        if rendered:
+            return rendered
+        text = self._readTarget(targetUrl, allowNetwork=allowNetwork)
+        lowered = text.lower()
+        if any(token in lowered for token in ("mfa required", "2fa", "verification code", "one-time code")):
+            return {
+                **self._blocked("mfaRequired", actionId=actionId, targetUrl=targetUrl),
+                "status": "needsProxy",
+                "requiresProxy": True,
+                "needsInput": [{"key": "mfaCode", "label": "Verification code", "secret": True}],
+                "steps": _portalStepsWithStatus(steps, "pending", reason="mfaRequired"),
+            }
+        if any(token in lowered for token in ("login required", "sign in required", "authentication required")):
+            return {
+                **self._blocked("loginRequired", actionId=actionId, targetUrl=targetUrl),
+                "status": "needsInput",
+                "needsInput": [{"key": "credentialRef", "label": "Credential reference", "secret": True}],
+                "steps": _portalStepsWithStatus(steps, "pending", reason="loginRequired"),
+            }
+        if "data-picux-portal=\"success\"" in lowered or "data-picux-portal='success'" in lowered or "claim submitted" in lowered or "form submitted" in lowered or "record retrieved" in lowered:
+            proofId = _stableToolId("portalProof", {"actionId": actionId, "targetUrl": targetUrl, "text": text[:500]})
+            completedSteps = _portalStepsWithStatus(steps, "succeeded", reason="")
+            outcome = _portalOutcome(text)
+            return {
+                "ok": True,
+                "tool": "portalBrowser",
+                "status": "succeeded",
+                "message": "Portal action completed.",
+                "portalActionId": actionId,
+                "targetUrl": targetUrl,
+                "steps": completedSteps,
+                "proof": {
+                    "proofId": proofId,
+                    "kind": "domSnapshot",
+                    "status": "captured",
+                    "label": "Portal completion snapshot",
+                    "artifactRef": proofId,
+                    "sourceUrl": targetUrl,
+                    "hash": "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest(),
+                    "meta": {"snippet": _redact(_stripTags(text)[:700]), "outcome": outcome},
+                },
+                "result": {**outcome, "sourceBound": True, "stepSummary": _portalStepSummary(completedSteps)},
+            }
+        return {**self._blocked("completionProofNotFound", actionId=actionId, targetUrl=targetUrl), "steps": _portalStepsWithStatus(steps, "attempted", reason="completionProofNotFound")}
+
+    def _runRendered(self, payload: dict[str, Any], *, targetUrl: str, actionId: str, steps: list[dict[str, Any]], allowNetwork: bool) -> dict[str, Any]:
+        parsed = urlparse(targetUrl)
+        if parsed.scheme not in {"http", "https"} or not allowNetwork:
+            return {}
+        command = self._renderedCommand()
+        if not command:
+            return {}
+        try:
+            completed = subprocess.run(
+                list(command),
+                input=json.dumps({**payload, "targetUrl": targetUrl, "portalActionId": actionId, "steps": steps, "timeoutMs": self.renderedTimeoutMs}, ensure_ascii=True),
+                capture_output=True,
+                check=False,
+                text=True,
+                timeout=max(12, int(self.renderedTimeoutMs / 1000) + 10),
+            )
+        except Exception as exc:
+            return {**self._blocked(f"renderedPortalCommandFailed:{str(exc)[:120]}", actionId=actionId, targetUrl=targetUrl), "steps": _portalStepsWithStatus(steps, "blocked", reason="renderedPortalCommandFailed")}
+        if completed.returncode != 0:
+            return {**self._blocked(f"renderedPortalCommandNonZero:{(completed.stderr or completed.stdout)[:120]}", actionId=actionId, targetUrl=targetUrl), "steps": _portalStepsWithStatus(steps, "blocked", reason="renderedPortalCommandNonZero")}
+        try:
+            result = json.loads(completed.stdout or "{}")
+        except Exception as exc:
+            return {**self._blocked(f"renderedPortalInvalidJson:{str(exc)[:120]}", actionId=actionId, targetUrl=targetUrl), "steps": _portalStepsWithStatus(steps, "blocked", reason="renderedPortalInvalidJson")}
+        if not isinstance(result, dict):
+            return {**self._blocked("renderedPortalInvalidResult", actionId=actionId, targetUrl=targetUrl), "steps": _portalStepsWithStatus(steps, "blocked", reason="renderedPortalInvalidResult")}
+        return {"tool": "portalBrowser", "portalActionId": actionId, "targetUrl": targetUrl, **result}
+
+    def _renderedCommand(self) -> tuple[str, ...]:
+        if self.renderedCommand:
+            return self.renderedCommand
+        script = Path(__file__).resolve().parents[3] / "scripts" / "picux-rendered-portal.mjs"
+        return ("node", str(script)) if script.exists() else ()
+
+    def _readTarget(self, targetUrl: str, *, allowNetwork: bool) -> str:
+        parsed = urlparse(targetUrl)
+        if parsed.scheme == "data":
+            raw = unquote_to_bytes(parsed.path.split(",", 1)[1] if "," in parsed.path else parsed.path)
+            return raw.decode("utf-8", errors="ignore")
+        if parsed.scheme in {"http", "https"} and allowNetwork:
+            req = Request(targetUrl, headers={"User-Agent": "PicuxPortalBrowser/0.1", "Accept": "text/html,application/xhtml+xml"})
+            with urlopen(req, timeout=self.timeoutSec) as response:
+                return response.read(500_000).decode("utf-8", errors="ignore")
+        return ""
+
+    @staticmethod
+    def _blocked(reason: str, *, actionId: str, targetUrl: str) -> dict[str, Any]:
+        return {
+            "ok": False,
+            "tool": "portalBrowser",
+            "status": "blocked",
+            "reason": reason,
+            "message": f"Portal action blocked: {reason}.",
+            "portalActionId": actionId,
+            "targetUrl": targetUrl,
+        }
+
+
+@dataclass(frozen=True)
+class MapTool:
+    """Source-bound local place search for HUNT/RESOLVE without fabricating places."""
+
+    timeoutSec: int = 6
+    fetcher: Any | None = None
+
+    def search(self, payload: dict[str, Any]) -> dict[str, Any]:
+        query = _query(payload)
+        entity = _serviceEntity(query, payload)
+        location = _placeLocation(query, payload)
+        radiusKm = _radiusKm(query, payload)
+        allowNetwork = bool(payload.get("allowNetwork", payload.get("live", False)))
+        supplied = payload.get("places", payload.get("results", []))
+        suppliedPlaces = supplied if isinstance(supplied, list) else []
+        if not entity or not location:
+            return self._result(
+                query=query,
+                provider="mapTool",
+                entity=entity,
+                location=location,
+                radiusKm=radiusKm,
+                places=[],
+                status="needsPlaceQuery",
+                allowNetwork=allowNetwork,
+                errors=["missing:entity" if not entity else "missing:location"],
+            )
+        if suppliedPlaces:
+            places = self._normalizeSuppliedPlaces(suppliedPlaces, entity=entity, location=location, radiusKm=radiusKm)
+            return self._result(query=query, provider="clientPlaces", entity=entity, location=location, radiusKm=radiusKm, places=places, status="found" if places else "searchedNoPlaces", allowNetwork=allowNetwork)
+
+        googleKey = str(
+            payload.get("googlePlacesApiKey")
+            or payload.get("googleMapsApiKey")
+            or os.environ.get("PICUX_GOOGLE_PLACES_API_KEY", "")
+            or os.environ.get("PICUX_GOOGLE_MAPS_API_KEY", "")
+            or os.environ.get("GOOGLE_PLACES_API_KEY", "")
+            or os.environ.get("GOOGLE_MAPS_API_KEY", "")
+            or ""
+        ).strip()
+        if googleKey:
+            try:
+                baseUrl = str(
+                    os.environ.get("PICUX_GOOGLE_PLACES_BASE_URL", "")
+                    or "https://maps.googleapis.com/maps/api/place"
+                ).rstrip("/")
+                places = self._googlePlaces(query=query, entity=entity, location=location, radiusKm=radiusKm, apiKey=googleKey, baseUrl=baseUrl)
+                return self._result(query=query, provider="googlePlaces", entity=entity, location=location, radiusKm=radiusKm, places=places, status="found" if places else "searchedNoPlaces", allowNetwork=True)
+            except Exception as exc:
+                return self._result(query=query, provider="googlePlaces", entity=entity, location=location, radiusKm=radiusKm, places=[], status="ioError", allowNetwork=True, errors=[str(exc)[:220]])
+
+        if not allowNetwork:
+            return self._result(query=query, provider="googlePlaces", entity=entity, location=location, radiusKm=radiusKm, places=[], status="needsPlacesApiKeyOrNetwork", allowNetwork=False, errors=["missing:GOOGLE_PLACES_API_KEY"])
+        try:
+            places = self._openStreetMap(query=query, entity=entity, location=location, radiusKm=radiusKm)
+            return self._result(query=query, provider="openStreetMapNominatim", entity=entity, location=location, radiusKm=radiusKm, places=places, status="found" if places else "searchedNoPlaces", allowNetwork=True)
+        except Exception as exc:
+            return self._result(query=query, provider="openStreetMapNominatim", entity=entity, location=location, radiusKm=radiusKm, places=[], status="ioError", allowNetwork=True, errors=[str(exc)[:220]])
+
+    def _googlePlaces(self, *, query: str, entity: str, location: str, radiusKm: float, apiKey: str, baseUrl: str) -> list[dict[str, Any]]:
+        searchText = _placeSearchText(entity, location)
+        url = f"{baseUrl}/textsearch/json?" + urlencode(
+            {
+                "query": searchText,
+                "radius": int(max(1.0, radiusKm) * 1000),
+                "key": apiKey,
+            }
+        )
+        data = self._fetchJson(url, headers={"Accept": "application/json"})
+        raw = data.get("results", []) if isinstance(data, dict) else []
+        places = []
+        for item in raw[:10]:
+            if not isinstance(item, dict):
+                continue
+            geo = item.get("geometry", {}) if isinstance(item.get("geometry"), dict) else {}
+            loc = geo.get("location", {}) if isinstance(geo.get("location"), dict) else {}
+            name = str(item.get("name", "") or "").strip()
+            address = str(item.get("formatted_address", item.get("vicinity", "")) or "").strip()
+            placeId = str(item.get("place_id", "") or "").strip()
+            details = self._googlePlaceDetails(placeId=placeId, apiKey=apiKey, baseUrl=baseUrl) if placeId else {}
+            sourceUrl = "https://www.google.com/maps/search/?" + urlencode({"api": "1", "query": f"{name} {address}".strip() or searchText, "query_place_id": placeId})
+            places.append(
+                _cleanPlace(
+                    {
+                        "placeId": placeId or _stableToolId("place", {"provider": "googlePlaces", "name": name, "address": address}),
+                        "name": name or str(details.get("name", "") or "").strip(),
+                        "category": _first(item.get("types", [])),
+                        "address": address or str(details.get("formatted_address", "") or "").strip(),
+                        "phone": details.get("international_phone_number") or details.get("formatted_phone_number") or "",
+                        "website": details.get("website") or "",
+                        "rating": item.get("rating", 0),
+                        "lat": loc.get("lat", 0),
+                        "lng": loc.get("lng", 0),
+                        "source": "googlePlaces",
+                        "sourceUrl": sourceUrl,
+                        "sourceBound": bool(placeId or sourceUrl),
+                        "entity": entity,
+                    }
+                )
+            )
+        return [place for place in places if place.get("name")]
+
+    def _googlePlaceDetails(self, *, placeId: str, apiKey: str, baseUrl: str) -> dict[str, Any]:
+        if not placeId:
+            return {}
+        fields = "name,formatted_phone_number,international_phone_number,formatted_address,address_components,website"
+        url = f"{baseUrl}/details/json?" + urlencode({"place_id": placeId, "fields": fields, "key": apiKey})
+        data = self._fetchJson(url, headers={"Accept": "application/json"})
+        result = data.get("result", {}) if isinstance(data, dict) else {}
+        return result if isinstance(result, dict) else {}
+
+    def _openStreetMap(self, *, query: str, entity: str, location: str, radiusKm: float) -> list[dict[str, Any]]:
+        searchText = _placeSearchText(entity, location)
+        url = "https://nominatim.openstreetmap.org/search?" + urlencode(
+            {
+                "format": "jsonv2",
+                "q": searchText,
+                "limit": 10,
+                "addressdetails": 1,
+            }
+        )
+        data = self._fetchJson(
+            url,
+            headers={
+                "Accept": "application/json",
+                "User-Agent": "PicuxMapTool/0.1 (source-bound local search; https://picux.ai)",
+            },
+        )
+        raw = data if isinstance(data, list) else []
+        places = []
+        for item in raw[:10]:
+            if not isinstance(item, dict):
+                continue
+            osmType = str(item.get("osm_type", "") or "").lower()
+            osmId = str(item.get("osm_id", "") or "")
+            placeId = str(item.get("place_id", "") or osmId or "")
+            name = str(item.get("name", "") or item.get("display_name", "") or "").strip()
+            address = str(item.get("display_name", "") or "").strip()
+            if osmType in {"node", "way", "relation"} and osmId:
+                sourceUrl = f"https://www.openstreetmap.org/{osmType}/{osmId}"
+            else:
+                sourceUrl = "https://www.openstreetmap.org/search?" + urlencode({"query": searchText})
+            places.append(
+                _cleanPlace(
+                    {
+                        "placeId": placeId or _stableToolId("place", {"provider": "openStreetMapNominatim", "name": name, "address": address}),
+                        "name": name,
+                        "category": str(item.get("type", item.get("class", "")) or ""),
+                        "address": address,
+                        "lat": item.get("lat", 0),
+                        "lng": item.get("lon", 0),
+                        "source": "openStreetMapNominatim",
+                        "sourceUrl": sourceUrl,
+                        "sourceBound": bool(placeId or sourceUrl),
+                        "entity": entity,
+                    }
+                )
+            )
+        return [place for place in places if place.get("name")]
+
+    def _normalizeSuppliedPlaces(self, raw: list[Any], *, entity: str, location: str, radiusKm: float) -> list[dict[str, Any]]:
+        places = []
+        for index, item in enumerate(raw[:20], start=1):
+            if not isinstance(item, dict):
+                continue
+            place = _cleanPlace({**item, "entity": str(item.get("entity", entity) or entity), "source": str(item.get("source", "clientPlaces") or "clientPlaces")})
+            if not place.get("placeId"):
+                place["placeId"] = _stableToolId("place", {"index": index, "name": place.get("name", ""), "address": place.get("address", ""), "sourceUrl": place.get("sourceUrl", "")})
+            place["sourceBound"] = bool(place.get("sourceUrl") or place.get("placeId"))
+            places.append(place)
+        return [place for place in places if place.get("name")]
+
+    def _fetchJson(self, url: str, *, headers: dict[str, str]) -> Any:
+        if self.fetcher:
+            return self.fetcher(url, headers)
+        request = Request(url, headers=headers)
+        with urlopen(request, timeout=self.timeoutSec) as response:
+            raw = response.read(500_000)
+        return json.loads(raw.decode("utf-8", errors="ignore") or "null")
+
+    @staticmethod
+    def _result(*, query: str, provider: str, entity: str, location: str, radiusKm: float, places: list[dict[str, Any]], status: str, allowNetwork: bool, errors: list[str] | None = None) -> dict[str, Any]:
+        return {
+            "ok": bool(places) or status in {"searchedNoPlaces", "needsPlacesApiKeyOrNetwork"},
+            "tool": "mapTool",
+            "provider": provider,
+            "status": status,
+            "query": {
+                "text": query,
+                "entity": entity,
+                "location": location,
+                "radiusKm": radiusKm,
+                "radiusMeters": int(max(1.0, radiusKm) * 1000),
+            },
+            "places": places,
+            "errors": errors or [],
+            "networkAttempted": allowNetwork,
+        }
+
+
+@dataclass(frozen=True)
+class SharedToolbox:
+    nlpTool: NLPTool = field(default_factory=NLPTool)
+    imageReader: ImageReader = field(default_factory=ImageReader)
+    browserReader: BrowserReader = field(default_factory=BrowserReader)
+    browserCheckout: BrowserCheckout = field(default_factory=BrowserCheckout)
+    portalBrowser: PortalBrowser = field(default_factory=PortalBrowser)
+    mapTool: MapTool = field(default_factory=MapTool)
+
+    def nlp(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.nlpTool.run(payload)
+
+    def readImage(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.imageReader.read(payload)
+
+    def readBrowser(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.browserReader.read(payload)
+
+    def checkoutBrowser(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.browserCheckout.run(payload)
+
+    def runPortal(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.portalBrowser.run(payload)
+
+    def searchMap(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self.mapTool.search(payload)
+
+
+def _query(payload: dict[str, Any]) -> str:
+    return str(payload.get("query", payload.get("request", payload.get("goal", payload.get("text", "")))) or "").strip()
+
+
+def _isLocalServiceQuery(query: str) -> bool:
+    lowered = _spellfixLocation(str(query or "")).lower()
+    serviceTerms = (
+        "mechanic",
+        "plumber",
+        "electrician",
+        "lawyer",
+        "consultant",
+        "doctor",
+        "dentist",
+        "cleaner",
+        "repair",
+        "garage",
+        "workshop",
+        "contractor",
+        "installer",
+        "handyman",
+        "agent",
+        "broker",
+        "small business",
+        "local business",
+    )
+    placeTerms = ("near", "nearby", "within", "around", "close to", "km", "kilometer", "kilometre", "hisingen", "goteborg", "gothenburg")
+    return any(term in lowered for term in serviceTerms) and any(term in lowered for term in placeTerms)
+
+
+def _isResolveCase(query: str) -> bool:
+    lowered = str(query or "").lower()
+    if any(token in lowered for token in ("dispute", "claim", "complaint", "broken", "damaged", "defective", "fake", "scam", "verify", "audit", "evidence", "receipt", "screenshot")):
+        return True
+    damagedDelivery = any(token in lowered for token in ("in-transit", "in transit", "transit", "delivery", "delivered")) and any(token in lowered for token in ("tv", "item", "goods", "package", "order"))
+    merchantNoFollowup = any(token in lowered for token in ("followup", "follow up", "follow-up", "did not follow", "no response", "customer representative", "customer represent"))
+    return damagedDelivery or merchantNoFollowup
+
+
+def _serviceEntity(query: str, payload: dict[str, Any]) -> str:
+    raw = str(payload.get("entity", payload.get("service", payload.get("businessType", ""))) or "").strip()
+    if raw:
+        return _cleanServiceEntity(raw)
+    lowered = _spellfixLocation(str(query or "")).lower()
+    known = (
+        "mechanic",
+        "plumber",
+        "electrician",
+        "lawyer",
+        "consultant",
+        "doctor",
+        "dentist",
+        "cleaner",
+        "garage",
+        "workshop",
+        "contractor",
+        "installer",
+        "handyman",
+        "broker",
+        "agent",
+    )
+    for item in known:
+        if re.search(rf"\b{re.escape(item)}s?\b", lowered):
+            return item
+    subject = re.search(
+        r"\b(?:need|find|search(?: for)?|locate|looking for|get)\s+(?:a|an|the|my|aa)?\s*(.+?)(?:\s+(?:within|near|nearby|around|close to|in)\b|$)",
+        lowered,
+        re.IGNORECASE,
+    )
+    if subject:
+        return _cleanServiceEntity(subject.group(1))
+    return ""
+
+
+def _cleanServiceEntity(value: str) -> str:
+    clean = re.sub(r"\b(?:a|an|the|my|aa|local|nearby|best|good|trusted)\b", " ", str(value or ""), flags=re.IGNORECASE)
+    clean = re.sub(r"[^A-Za-z0-9 &/-]+", " ", clean)
+    clean = re.sub(r"\s+", " ", clean).strip().lower()
+    return clean[:80]
+
+
+def _placeLocation(query: str, payload: dict[str, Any]) -> str:
+    raw = str(payload.get("location", payload.get("near", payload.get("area", ""))) or "").strip()
+    if raw:
+        return _spellfixLocation(raw)
+    fixed = _spellfixLocation(str(query or ""))
+    patterns = (
+        r"\bwithin\s+[0-9]+(?:[,.][0-9]+)?\s*(?:km|kilometers?|kilometres?)\s+(?:of|from)\s+(.+)$",
+        r"\b(?:near|nearby|around|close to|in)\s+(.+)$",
+    )
+    for pattern in patterns:
+        match = re.search(pattern, fixed, re.IGNORECASE)
+        if not match:
+            continue
+        location = match.group(1)
+        location = re.split(r"\b(?:for|with|that|who|and then)\b", location, maxsplit=1, flags=re.IGNORECASE)[0]
+        location = re.sub(r"[.?!]+$", "", location).strip(" ,")
+        if location:
+            return location[:140]
+    return ""
+
+
+def _radiusKm(query: str, payload: dict[str, Any]) -> float:
+    raw = payload.get("radiusKm", payload.get("distanceKm", payload.get("radius", "")))
+    try:
+        if raw not in {"", None}:
+            value = float(str(raw).replace(",", "."))
+            if value > 0:
+                return round(min(100.0, value), 2)
+    except Exception:
+        pass
+    match = re.search(r"\b(?:within|inside|under|less than)?\s*([0-9]+(?:[,.][0-9]+)?)\s*(?:km|kilometers?|kilometres?)\b", str(query or ""), re.IGNORECASE)
+    if match:
+        return round(min(100.0, float(match.group(1).replace(",", "."))), 2)
+    return 10.0
+
+
+def _spellfixLocation(value: str) -> str:
+    fixed = str(value or "")
+    replacements = {
+        "hisigen": "Hisingen",
+        "hissigen": "Hisingen",
+        "hissingen": "Hisingen",
+        "goteborg": "Goteborg",
+        "gothenburg": "Goteborg",
+    }
+    for wrong, right in replacements.items():
+        fixed = re.sub(rf"\b{wrong}\b", right, fixed, flags=re.IGNORECASE)
+    return fixed
+
+
+def _placeSearchText(entity: str, location: str) -> str:
+    cleanEntity = str(entity or "").strip().lower()
+    cleanLocation = _spellfixLocation(str(location or "").strip())
+    locationLower = cleanLocation.lower()
+    if cleanEntity == "mechanic" and any(token in locationLower for token in ("hisingen", "goteborg", "sweden", "stockholm", "malmo")):
+        return f"bilverkstad {cleanLocation}".strip()
+    if cleanEntity == "mechanic":
+        return f"car repair {cleanLocation}".strip()
+    return f"{cleanEntity} near {cleanLocation}".strip()
+
+
+def _cleanPlace(raw: dict[str, Any]) -> dict[str, Any]:
+    place = {
+        "placeId": str(raw.get("placeId", raw.get("place_id", raw.get("id", ""))) or ""),
+        "name": re.sub(r"\s+", " ", str(raw.get("name", raw.get("title", "")) or "")).strip()[:220],
+        "category": str(raw.get("category", raw.get("type", "")) or "")[:120],
+        "address": re.sub(r"\s+", " ", str(raw.get("address", raw.get("formatted_address", "")) or "")).strip()[:300],
+        "phone": str(raw.get("phone", raw.get("phoneNumber", raw.get("international_phone_number", ""))) or "")[:80],
+        "website": str(raw.get("website", raw.get("url", "")) or "")[:600],
+        "rating": _safeFloat(raw.get("rating", 0.0)),
+        "lat": _safeFloat(raw.get("lat", raw.get("latitude", 0.0))),
+        "lng": _safeFloat(raw.get("lng", raw.get("lon", raw.get("longitude", 0.0)))),
+        "distanceKm": _safeFloat(raw.get("distanceKm", raw.get("distance_km", 0.0))),
+        "source": str(raw.get("source", raw.get("provider", "mapTool")) or "mapTool")[:80],
+        "sourceUrl": str(raw.get("sourceUrl", raw.get("mapsUrl", raw.get("url", ""))) or "")[:600],
+        "sourceBound": bool(raw.get("sourceBound", raw.get("sourceUrl", raw.get("placeId", raw.get("place_id", ""))))),
+        "entity": str(raw.get("entity", raw.get("service", "")) or "")[:80],
+    }
+    if not place["sourceUrl"] and place["lat"] and place["lng"]:
+        place["sourceUrl"] = "https://www.google.com/maps/search/?" + urlencode({"api": "1", "query": f"{place['lat']},{place['lng']}"})
+        place["sourceBound"] = True
+    return place
+
+
+def _first(value: Any) -> str:
+    if isinstance(value, list):
+        for item in value:
+            clean = str(item or "").strip()
+            if clean:
+                return clean
+    return str(value or "").strip()
+
+
+def _route(query: str, *, seed: str) -> list[str]:
+    lowered = query.lower()
+    localService = _isLocalServiceQuery(query)
+    explicitResolve = _isResolveCase(query)
+    explicitProxy = any(token in lowered for token in ("place a call", "make a call", "call merchant", "call support", "human", "lawyer", "consultant", "manual review", "logistics", "pickup", "delivery"))
+    explicitPay = any(token in lowered for token in ("pay", "payment", "settle", "settlement", "escrow"))
+    if seed == "pay" and not explicitPay:
+        seed = "resolve" if explicitResolve else "hunt"
+    if seed == "proxy" and not explicitProxy:
+        seed = "resolve" if explicitResolve else "hunt"
+    if explicitResolve and seed in {"hunt", "bridge"}:
+        seed = "resolve"
+    route = [seed] if seed in SHARED_DOMAINS else ["hunt"]
+    if not explicitResolve and (localService or any(token in lowered for token in ("find", "near", "within", "km", "buy", "shop", "shopping", "best", "option", "lead", "opportunity", "source", "market", "property", "apartment", "house", "mechanic", "plumber", "electrician", "repair"))) and "hunt" not in route:
+        route.insert(0, "hunt")
+    if any(token in lowered for token in ("email", "merchant", "bank", "service", "support", "api", "webhook", "connector", "whatsapp", "chat", "gmail", "slack", "jira", "notion", "sap", "representative", "followup", "follow up")) and "bridge" not in route:
+        route.append("bridge")
+    if explicitResolve and "resolve" not in route:
+        route.append("resolve")
+    if explicitProxy and "proxy" not in route:
+        route.append("proxy")
+    if explicitPay and "pay" not in route:
+        route.append("pay")
+    if "pay" in route and "resolve" not in route:
+        route.insert(max(1, route.index("pay")), "resolve")
+    unique = list(dict.fromkeys([item for item in route if item in SHARED_DOMAINS]))
+    order = ["resolve", "bridge", "proxy", "pay", "hunt"] if explicitResolve and "hunt" not in unique else ["hunt", "bridge", "resolve", "proxy", "pay"]
+    return [domain for domain in order if domain in unique]
+
+
+def _entities(query: str, payload: dict[str, Any]) -> dict[str, Any]:
+    serviceEntity = _serviceEntity(query, payload)
+    return {
+        "item": _item(query),
+        "entity": serviceEntity,
+        "service": serviceEntity,
+        "location": _placeLocation(query, payload),
+        "radiusKm": _radiusKm(query, payload),
+        "budgetUsd": _budget(query, payload),
+        "target": _target(query),
+        "phone": _phone(query, payload),
+        "email": _email(query),
+        "market": _market(query),
+        "country": _country(query, payload),
+        "region": _region(query, payload),
+        "locale": str(payload.get("locale", "") or ""),
+        "budgetCurrency": _budgetCurrency(query, payload),
+    }
+
+
+def _intentKind(query: str) -> str:
+    lowered = query.lower()
+    if _isLocalServiceQuery(query):
+        return "localService"
+    if _isResolveCase(query):
+        return "dispute"
+    if any(token in lowered for token in ("buy", "shop", "shopping", "property", "house", "apartment")):
+        return "discovery"
+    if any(token in lowered for token in ("claim", "dispute", "damaged", "broken", "scam", "fake")):
+        return "dispute"
+    if any(token in lowered for token in ("call merchant", "call support", "human", "logistics")):
+        return "handoff"
+    return "general"
+
+
+def _confidence(query: str, route: list[str], entities: dict[str, Any]) -> float:
+    score = 0.45 + min(0.25, len(route) * 0.05)
+    if entities.get("item") or entities.get("target"):
+        score += 0.12
+    if entities.get("budgetUsd") or entities.get("phone") or entities.get("email"):
+        score += 0.10
+    if len(query.split()) >= 5:
+        score += 0.08
+    return round(min(0.96, score), 3)
+
+
+def _stripTags(text: str) -> str:
+    clean = re.sub(r"<script\b[^>]*>.*?</script>", " ", str(text or ""), flags=re.IGNORECASE | re.DOTALL)
+    clean = re.sub(r"<style\b[^>]*>.*?</style>", " ", clean, flags=re.IGNORECASE | re.DOTALL)
+    clean = re.sub(r"<[^>]+>", " ", clean)
+    return html.unescape(re.sub(r"\s+", " ", clean)).strip()
+
+
+def _confirmation(text: str) -> str:
+    clean = _stripTags(text)
+    match = re.search(r"\bconfirmation\s*(?:number|no|id|#)\s*[:#-]?\s*([A-Z0-9-]{4,32})\b", clean, re.IGNORECASE)
+    if match:
+        return match.group(1)
+    match = re.search(r"\b(?:case|claim|ticket|reference|order)\s*(?:number|no|id|#)\s*[:#-]?\s*([A-Z0-9-]{4,32})\b", clean, re.IGNORECASE)
+    return match.group(1) if match else ""
+
+
+def _portalOutcome(text: str) -> dict[str, Any]:
+    clean = _stripTags(text)
+    confirmation = _confirmation(clean)
+    status = _portalStatus(clean)
+    deadline = _firstMatch(clean, (r"\b(?:deadline|due date|respond by|follow[- ]?up by)\s*[:#-]?\s*([A-Z][a-z]{2,9}\s+\d{1,2},?\s+\d{4}|\d{4}-\d{2}-\d{2}|\d{1,2}/\d{1,2}/\d{2,4})",))
+    amount = _firstMatch(clean, (r"\b(?:amount|refund|claim value|total)\s*[:#-]?\s*([A-Z]{3}\s*)?([$€£]?\s*\d+(?:[,.]\d{2})?)",))
+    recordRefs = []
+    for pattern in (
+        r"\b(?:case|claim|ticket|reference|order)\s*(?:number|no|id|#)\s*[:#-]?\s*([A-Z0-9-]{4,32})\b",
+        r"\b(?:tracking|shipment)\s*(?:number|no|id|#)\s*[:#-]?\s*([A-Z0-9-]{4,32})\b",
+    ):
+        for match in re.finditer(pattern, clean, re.IGNORECASE):
+            recordRefs.append(match.group(1))
+    return {
+        "confirmation": confirmation,
+        "status": status,
+        "deadline": deadline,
+        "amount": amount,
+        "recordRefs": list(dict.fromkeys(recordRefs)),
+    }
+
+
+def _portalStatus(text: str) -> str:
+    match = re.search(r"\b(?:status|state)\s*[:#-]?\s*([A-Za-z][A-Za-z -]{2,32})\b", text, re.IGNORECASE)
+    if match:
+        return match.group(1).strip(" .").lower().replace(" ", "_")
+    lowered = text.lower()
+    for label, tokens in (
+        ("submitted", ("claim submitted", "form submitted", "submitted")),
+        ("approved", ("approved", "accepted")),
+        ("rejected", ("rejected", "denied")),
+        ("pending", ("pending", "under review", "in review", "awaiting")),
+        ("retrieved", ("record retrieved", "record found", "download ready")),
+    ):
+        if any(token in lowered for token in tokens):
+            return label
+    return ""
+
+
+def _firstMatch(text: str, patterns: tuple[str, ...]) -> str:
+    for pattern in patterns:
+        match = re.search(pattern, text, re.IGNORECASE)
+        if not match:
+            continue
+        groups = [item for item in match.groups() if item]
+        value = " ".join(groups).strip() if groups else match.group(0).strip()
+        return re.sub(r"\s+", " ", value)
+    return ""
+
+
+def _portalStepResults(raw: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw, list):
+        return []
+    steps = []
+    for index, item in enumerate(raw, start=1):
+        if not isinstance(item, dict):
+            continue
+        stepId = str(item.get("stepId", "") or _stableToolId("portalStep", {"index": index, "step": item}))
+        steps.append(
+            {
+                "stepId": stepId,
+                "label": str(item.get("label", item.get("action", f"Step {index}")) or f"Step {index}"),
+                "action": str(item.get("action", "") or ""),
+                "selector": str(item.get("selector", "") or ""),
+                "valueKey": str(item.get("valueKey", "") or ""),
+                "status": str(item.get("status", "pending") or "pending"),
+                "proofRequired": bool(item.get("proofRequired", False)),
+                "meta": item.get("meta", {}) if isinstance(item.get("meta"), dict) else {},
+            }
+        )
+    return steps
+
+
+def _portalRequiredInputs(payload: dict[str, Any], steps: list[dict[str, Any]]) -> list[str]:
+    meta = payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {}
+    required = meta.get("requiredInputs", payload.get("requiredInputs", []))
+    if isinstance(required, list):
+        clean = [str(item) for item in required if str(item)]
+        if clean:
+            return clean
+    return [str(step.get("valueKey", "") or "") for step in steps if str(step.get("valueKey", "") or "")]
+
+
+def _missingPortalInputs(steps: list[dict[str, Any]], inputs: dict[str, Any], *, requiredKeys: list[str]) -> list[dict[str, Any]]:
+    missing = []
+    required = set(requiredKeys)
+    for step in steps:
+        key = str(step.get("valueKey", "") or "")
+        if not key or key not in required:
+            continue
+        if key not in inputs or _emptyPortalInput(inputs.get(key)):
+            missing.append({"key": key, "label": str(step.get("label", key) or key), "secret": False})
+    deduped: dict[str, dict[str, Any]] = {}
+    for item in missing:
+        deduped[item["key"]] = item
+    return list(deduped.values())
+
+
+def _emptyPortalInput(value: Any) -> bool:
+    return value is None or value == "" or value == []
+
+
+def _portalStepsWithMissingInputs(steps: list[dict[str, Any]], missing: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    missingKeys = {str(item.get("key", "") or "") for item in missing}
+    result = []
+    for step in steps:
+        valueKey = str(step.get("valueKey", "") or "")
+        status = "needsInput" if valueKey and valueKey in missingKeys else str(step.get("status", "pending") or "pending")
+        result.append({**step, "status": status, "meta": {**(step.get("meta", {}) if isinstance(step.get("meta"), dict) else {}), "missingInput": valueKey in missingKeys}})
+    return result
+
+
+def _portalStepsWithStatus(steps: list[dict[str, Any]], status: str, *, reason: str) -> list[dict[str, Any]]:
+    result = []
+    for step in steps:
+        meta = step.get("meta", {}) if isinstance(step.get("meta"), dict) else {}
+        if reason:
+            meta = {**meta, "reason": reason}
+        result.append({**step, "status": status, "meta": meta})
+    return result
+
+
+def _portalStepSummary(steps: list[dict[str, Any]]) -> dict[str, Any]:
+    counts: dict[str, int] = {}
+    for step in steps:
+        status = str(step.get("status", "") or "")
+        counts[status] = counts.get(status, 0) + 1
+    return {"total": len(steps), "byStatus": counts}
+
+
+def _stableToolId(prefix: str, payload: dict[str, Any]) -> str:
+    digest = hashlib.sha256(json.dumps(payload, ensure_ascii=True, sort_keys=True).encode("utf-8")).hexdigest()
+    return f"{prefix}_{digest[:24]}"
+
+
+def _looksLikeFollowUp(query: str) -> bool:
+    lowered = query.lower()
+    return any(token in lowered for token in ("yes", "no", "continue", "approve", "use that", "same", "also", "the second", "that one", "go ahead"))
+
+
+def _imageInputs(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    raw = []
+    for key in ("images", "attachments", "documents"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            raw.extend(item for item in value if isinstance(item, dict))
+    images = []
+    seen = set()
+    for item in raw:
+        mime = str(item.get("mime", item.get("contentType", "")) or "").lower()
+        kind = str(item.get("kind", item.get("type", "")) or "").lower()
+        if mime.startswith("image/") or kind in {"image", "photo", "screenshot"} or any(key in item for key in ("base64", "contentBase64", "dataUrl")):
+            key = "|".join(str(item.get(name, "") or "") for name in ("artifactId", "name", "dataUrl", "base64", "contentBase64", "text", "ocr"))
+            if key and key in seen:
+                continue
+            if key:
+                seen.add(key)
+            images.append(item)
+    return images
+
+
+def _imageBytes(image: dict[str, Any]) -> bytes:
+    raw = str(image.get("base64", image.get("contentBase64", image.get("data", ""))) or "")
+    dataUrl = str(image.get("dataUrl", "") or "")
+    if dataUrl and "," in dataUrl:
+        raw = dataUrl.split(",", 1)[1]
+    if not raw:
+        return b""
+    try:
+        return base64.b64decode(raw, validate=False)
+    except Exception:
+        return raw.encode("utf-8", errors="ignore")
+
+
+def _imageText(image: dict[str, Any], rawBytes: bytes) -> str:
+    fields = [str(image.get(key, "") or "") for key in ("text", "alt", "caption", "ocr", "description", "name")]
+    printable = ""
+    if rawBytes:
+        printable = " ".join(match.decode("utf-8", errors="ignore") for match in re.findall(rb"[ -~]{5,}", rawBytes))
+    ocr = _ocrText(image, rawBytes)
+    return " ".join(item for item in [*fields, printable, ocr] if item).strip()
+
+
+def _ocrText(image: dict[str, Any], rawBytes: bytes) -> str:
+    if not rawBytes or not shutil.which("tesseract"):
+        return ""
+    mime = str(image.get("mime", image.get("contentType", "")) or "").lower()
+    name = str(image.get("name", image.get("filename", "")) or "").lower()
+    suffix = ".png"
+    if "jpeg" in mime or "jpg" in mime or name.endswith((".jpg", ".jpeg")):
+        suffix = ".jpg"
+    elif "webp" in mime or name.endswith(".webp"):
+        suffix = ".webp"
+    elif "tiff" in mime or name.endswith((".tif", ".tiff")):
+        suffix = ".tif"
+    path = ""
+    try:
+        with tempfile.NamedTemporaryFile(prefix="picux-image-", suffix=suffix, delete=False) as tmp:
+            tmp.write(rawBytes)
+            path = tmp.name
+        completed = subprocess.run(
+            ["tesseract", path, "stdout", "--dpi", "150"],
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=8,
+        )
+        if completed.returncode == 0:
+            return re.sub(r"\s+", " ", completed.stdout or "").strip()
+        return ""
+    except Exception:
+        return ""
+    finally:
+        if path:
+            try:
+                Path(path).unlink(missing_ok=True)
+            except Exception:
+                pass
+
+
+def _matches(query: str, text: str) -> list[str]:
+    qTokens = {token for token in re.findall(r"[a-z0-9]+", query.lower()) if len(token) > 2}
+    lowered = text.lower()
+    matches = [token for token in sorted(qTokens) if token in lowered]
+    for label, tokens in {
+        "receipt": ("receipt", "invoice", "order", "total"),
+        "damage": ("broken", "damaged", "crack", "scratch"),
+        "identity": ("name", "seller", "merchant", "store"),
+    }.items():
+        if any(token in lowered for token in tokens) and label not in matches:
+            matches.append(label)
+    return matches[:12]
+
+
+def _summary(text: str, matches: list[str]) -> str:
+    if not text:
+        return "No readable image text was available; preserve the image as source evidence."
+    prefix = "Matched " + ", ".join(matches[:4]) + ". " if matches else ""
+    clean = re.sub(r"\s+", " ", _redact(text)).strip()
+    return (prefix + clean[:220]).strip()
+
+
+def _privateTargetBlockReason(url: str, *, allowPrivateNetwork: bool = False) -> str:
+    if allowPrivateNetwork:
+        return ""
+    parsed = urlparse(str(url or ""))
+    if parsed.scheme not in {"http", "https"}:
+        return ""
+    host = (parsed.hostname or "").strip().lower()
+    if not host:
+        return "privateNetworkTargetBlocked"
+    if host == "localhost" or host.endswith(".localhost") or host.endswith(".local"):
+        return "privateNetworkTargetBlocked"
+    try:
+        ip = ipaddress.ip_address(host.strip("[]"))
+    except ValueError:
+        return ""
+    if ip.is_loopback or ip.is_private or ip.is_link_local or ip.is_unspecified or ip.is_reserved:
+        return "privateNetworkTargetBlocked"
+    return ""
+
+
+def _blockedUrlObservation(url: str, query: str, *, source: str, error: str) -> dict[str, Any]:
+    return {
+        "source": source,
+        "url": url,
+        "ok": False,
+        "adapter": "http",
+        "statusCode": 0,
+        "title": "",
+        "snippets": [],
+        "textSample": "",
+        "matched": False,
+        "error": error,
+    }
+
+
+def _pageObservation(url: str, text: str, query: str, adapter: str, *, source: str, statusCode: int) -> dict[str, Any]:
+    title = _title(text)
+    body = _stripHtml(text)
+    snippets = _snippets(body, query)
+    return {
+        "source": source,
+        "url": url,
+        "ok": True,
+        "adapter": adapter,
+        "statusCode": statusCode,
+        "title": title,
+        "snippets": snippets,
+        "textSample": _redact(body[:4000]),
+        "matched": bool(snippets),
+    }
+
+
+def _title(text: str) -> str:
+    match = re.search(r"<title[^>]*>(.*?)</title>", text, flags=re.IGNORECASE | re.DOTALL)
+    if not match:
+        return ""
+    return html.unescape(re.sub(r"\s+", " ", match.group(1))).strip()[:160]
+
+
+def _stripHtml(text: str) -> str:
+    clean = re.sub(r"<script\b.*?</script>", " ", text, flags=re.IGNORECASE | re.DOTALL)
+    clean = re.sub(r"<style\b.*?</style>", " ", clean, flags=re.IGNORECASE | re.DOTALL)
+    clean = re.sub(r"<[^>]+>", " ", clean)
+    return html.unescape(re.sub(r"\s+", " ", clean)).strip()
+
+
+def _snippets(text: str, query: str) -> list[str]:
+    tokens = [token for token in re.findall(r"[a-z0-9]+", query.lower()) if len(token) > 2]
+    lowered = text.lower()
+    snippets = []
+    for token in tokens[:8]:
+        idx = lowered.find(token)
+        if idx < 0:
+            continue
+        start = max(0, idx - 90)
+        end = min(len(text), idx + 180)
+        snippet = text[start:end].strip()
+        if snippet and snippet not in snippets:
+            snippets.append(snippet)
+    return snippets[:5]
+
+
+def _marketplaceSet(query: str, entities: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+    raw = payload.get("marketplaces", payload.get("sources", []))
+    requested = [_sourceAlias(str(item).strip().lower()) for item in raw if str(item).strip()] if isinstance(raw, list) else []
+    market = str(entities.get("market", "") or "")
+    country = _country(query, {**payload, **entities})
+    if not requested:
+        requested = _marketplaceSources(market, country)
+    return {
+        "market": market or "shopping",
+        "country": country,
+        "localSources": _localSources(market, country),
+        "sources": requested,
+    }
+
+
+def _targetLimit(payload: dict[str, Any]) -> int:
+    try:
+        raw = int(payload.get("targetLimit", payload.get("sourceLimit", 12)) or 12)
+    except Exception:
+        raw = 12
+    return max(1, min(raw, 20))
+
+
+def _searchTargets(query: str, entities: dict[str, Any], payload: dict[str, Any], *, marketplaceSet: dict[str, Any] | None = None) -> list[dict[str, str]]:
+    marketplaceSet = marketplaceSet or _marketplaceSet(query, entities, payload)
+    requested = [str(item) for item in marketplaceSet.get("sources", []) if str(item)]
+    item = quote_plus(str(entities.get("item", "") or query))
+    templates = {
+        "ebay": "https://www.ebay.com/sch/i.html?_nkw={q}",
+        "facebook": "https://www.facebook.com/marketplace/search/?query={q}",
+        "alibaba": "https://www.alibaba.com/trade/search?SearchText={q}",
+        "amazon": "https://www.amazon.com/s?k={q}",
+        "shopify": "https://shop.app/search?q={q}",
+        "blocket": "https://www.blocket.se/annonser/hela_sverige?q={q}",
+        "tradera": "https://www.tradera.com/search?q={q}",
+        "jumia": "https://www.jumia.com.ng/catalog/?q={q}",
+        "konga": "https://www.konga.com/search?search={q}",
+        "jiji": "https://jiji.ng/search?query={q}",
+        "craigslist": "https://www.craigslist.org/search/sss?query={q}",
+        "gumtree": "https://www.gumtree.com/search?search_category=all&q={q}",
+        "zillow": "https://www.zillow.com/homes/{q}_rb/",
+        "redfin": "https://www.redfin.com/city/30749/CA/{q}",
+        "hemnet": "https://www.hemnet.se/bostader?query={q}",
+    }
+    homeUrls = {
+        "amazon": "https://www.amazon.com/",
+        "ebay": "https://www.ebay.com/",
+        "facebook": "https://www.facebook.com/marketplace/",
+        "alibaba": "https://www.alibaba.com/",
+        "shopify": "https://shop.app/",
+        "blocket": "https://www.blocket.se/",
+        "tradera": "https://www.tradera.com/",
+        "jumia": "https://www.jumia.com.ng/",
+        "konga": "https://www.konga.com/",
+        "jiji": "https://jiji.ng/",
+    }
+    return [
+        {
+            "source": source,
+            "url": templates.get(source, f"https://www.google.com/search?q={item}+{quote_plus(source)}").format(q=item),
+            "homeUrl": homeUrls.get(source, ""),
+            "kind": "marketplaceSearch",
+        }
+        for source in requested[:10]
+    ]
+
+
+def _sourceAlias(source: str) -> str:
+    aliases = {
+        "fb": "facebook",
+        "facebook marketplace": "facebook",
+        "facebook_marketplace": "facebook",
+        "ali": "alibaba",
+        "aliexpress": "alibaba",
+        "shop": "shopify",
+        "shop.app": "shopify",
+        "blocket.se": "blocket",
+        "tradera.se": "tradera",
+        "jumia nigeria": "jumia",
+        "jumia.com.ng": "jumia",
+        "konga.com": "konga",
+        "jiji.ng": "jiji",
+    }
+    return aliases.get(source, source)
+
+
+def _marketplaceSources(market: str, country: str) -> list[str]:
+    if market == "property":
+        local = _localSources(market, country)
+        return _unique([*local, "zillow", "redfin", "hemnet"])
+    local = _localSources("shopping", country)
+    globalSources = ["ebay", "facebook", "alibaba", "amazon", "shopify"]
+    if not local:
+        return [*globalSources, "blocket"]
+    return _unique([*local, *globalSources])
+
+
+def _localSources(market: str, country: str) -> list[str]:
+    if market == "property":
+        return {
+            "se": ["hemnet", "blocket"],
+            "ng": ["propertypro", "jiji"],
+            "uk": ["rightmove", "zoopla", "gumtree"],
+            "us": ["zillow", "redfin", "craigslist"],
+        }.get(country, [])
+    return {
+        "se": ["blocket", "tradera", "facebook"],
+        "ng": ["jumia", "konga", "jiji", "facebook"],
+        "uk": ["gumtree", "facebook", "ebay"],
+        "us": ["craigslist", "facebook", "ebay", "amazon"],
+    }.get(country, [])
+
+
+def _unique(items: list[str]) -> list[str]:
+    return list(dict.fromkeys(item for item in items if item))
+
+
+def _dedupeTargets(targets: list[dict[str, str]]) -> list[dict[str, str]]:
+    seen = set()
+    out = []
+    for target in targets:
+        url = str(target.get("url", "") or "")
+        if not url or url in seen:
+            continue
+        seen.add(url)
+        out.append(target)
+    return out
+
+
+def _attemptSummaries(observations: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    summaries = []
+    for observation in observations:
+        summaries.append(
+            {
+                "source": observation.get("source", ""),
+                "url": observation.get("url", ""),
+                "ok": bool(observation.get("ok")),
+                "adapter": observation.get("adapter", ""),
+                "statusCode": observation.get("statusCode", 0),
+                "title": observation.get("title", ""),
+                "matched": bool(observation.get("matched")),
+                "listingCount": len(observation.get("listings", [])) if isinstance(observation.get("listings"), list) else 0,
+                "filteredListingCount": int(observation.get("filteredListingCount", 0) or 0),
+                "search": observation.get("search", {}) if isinstance(observation.get("search"), dict) else {},
+                "error": observation.get("error", ""),
+            }
+        )
+    return summaries
+
+
+def _renderedSkipped(reason: str, error: str = "") -> dict[str, Any]:
+    attempted = reason not in {"notRequested", "noTargets"}
+    meta = {
+        "attempted": attempted,
+        "available": False,
+        "status": "skipped" if not attempted else "unavailable",
+        "fallbackReason": reason,
+        "adapter": "playwrightChromium",
+    }
+    if error:
+        meta["error"] = error
+    return {"observations": [], "meta": meta}
+
+
+def _normalizeRenderedObservations(raw: Any, query: str) -> list[dict[str, Any]]:
+    if not isinstance(raw, list):
+        return []
+    observations: list[dict[str, Any]] = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        source = str(item.get("source", "source") or "source")
+        url = str(item.get("url", "") or "")
+        adapter = str(item.get("adapter", "playwrightChromium") or "playwrightChromium")
+        statusCode = _safeInt(item.get("statusCode", 0))
+        title = str(item.get("title", "") or "")[:180]
+        text = re.sub(r"\s+", " ", str(item.get("textSample", item.get("text", "")) or "")).strip()
+        textSample = _redact(text[:8000])
+        snippets = _snippets(f"{title} {textSample}", query)
+        listings = _normalizeListings(item.get("listings", []))
+        search = _normalizeSearch(item.get("search", {}))
+        if not item.get("ok"):
+            observations.append(
+                {
+                    "source": source,
+                    "url": url,
+                    "ok": False,
+                    "adapter": adapter,
+                    "statusCode": statusCode,
+                    "title": title,
+                    "error": str(item.get("error", "") or "")[:220],
+                    "snippets": snippets,
+                    "textSample": textSample,
+                    "listings": listings,
+                    "search": search,
+                    "matched": bool(snippets),
+                }
+            )
+            continue
+        observations.append(
+            {
+                "source": source,
+                "url": url,
+                "ok": True,
+                "adapter": adapter,
+                "statusCode": statusCode,
+                "title": title,
+                "snippets": snippets,
+                "textSample": textSample,
+                "listings": listings,
+                "search": search,
+                "matched": bool(snippets),
+            }
+        )
+    return observations
+
+
+def _safeInt(value: Any) -> int:
+    try:
+        return int(value or 0)
+    except Exception:
+        return 0
+
+
+def _safeFloat(value: Any) -> float:
+    try:
+        return float(value or 0.0)
+    except Exception:
+        return 0.0
+
+
+def _normalizeListings(raw: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw, list):
+        return []
+    listings = []
+    for item in raw:
+        if not isinstance(item, dict):
+            continue
+        title = re.sub(r"\s+", " ", str(item.get("title", "") or "")).strip()
+        priceText = re.sub(r"\s+", " ", str(item.get("priceText", "") or "")).strip()
+        url = str(item.get("url", "") or "").strip()
+        textSample = re.sub(r"\s+", " ", str(item.get("textSample", "") or "")).strip()
+        if not priceText:
+            priceText = _listingPriceText(textSample)
+        if not title:
+            title = _listingTitleText(textSample, priceText)
+        if not title and not priceText:
+            continue
+        listings.append(
+            {
+                "title": _redact(title[:220]),
+                "priceText": _redact(priceText[:120]),
+                "url": url[:600],
+                "textSample": _redact(textSample[:900]),
+            }
+        )
+    return listings[:18]
+
+
+def _listingTitleText(text: str, priceText: str = "") -> str:
+    raw = re.sub(r"\s+", " ", str(text or "")).strip()
+    if not raw:
+        return ""
+    if priceText:
+        priceAt = raw.find(priceText)
+        if priceAt > 0:
+            raw = raw[:priceAt]
+    raw = re.sub(r"^(?:NEW LOW PRICE|SPONSORED|Shop on eBay|Brand New)+", "", raw, flags=re.IGNORECASE).strip()
+    for marker in (
+        "Pre-Owned",
+        "Open Box",
+        "Brand New",
+        "New Other",
+        "Buy It Now",
+        "or Best Offer",
+        "out of 5 stars",
+        "product ratings",
+    ):
+        index = raw.lower().find(marker.lower())
+        if index > 8:
+            raw = raw[:index]
+            break
+    raw = re.sub(r"\s+", " ", raw).strip(" -·")
+    return _redact(raw[:220])
+
+
+def _listingPriceText(text: str) -> str:
+    raw = str(text or "")
+    patterns = (
+        r"(?:USD|SEK|NGN|NOK|EUR|GBP|\$|€|£|₦)\s*[0-9][0-9\s,.]*(?:[,.][0-9]{1,2})?",
+        r"[0-9][0-9\s,.]*(?:[,.][0-9]{1,2})?\s*(?:kr|kronor|sek|usd|dollars?|ngn|naira|€|£|₦)",
+    )
+    for pattern in patterns:
+        match = re.search(pattern, raw, flags=re.IGNORECASE)
+        if match:
+            value = re.sub(r"\s+", " ", match.group(0)).strip()
+            return value[:120]
+    return ""
+
+
+def _normalizeSearch(raw: Any) -> dict[str, Any]:
+    raw = raw if isinstance(raw, dict) else {}
+    return {
+        "mode": str(raw.get("mode", "") or ""),
+        "query": _redact(str(raw.get("query", "") or "")[:220]),
+        "submitted": bool(raw.get("submitted")),
+        "inputSelector": str(raw.get("inputSelector", "") or "")[:160],
+        "entryUrl": str(raw.get("entryUrl", "") or "")[:600],
+        "fallbackUrl": str(raw.get("fallbackUrl", "") or "")[:600],
+        "fallbackReason": str(raw.get("fallbackReason", "") or "")[:220],
+    }
+
+
+def _offersFromObservations(observations: list[dict[str, Any]], query: str, entities: dict[str, Any], *, budget: dict[str, Any], fxRates: dict[str, float]) -> list[dict[str, Any]]:
+    offers: list[dict[str, Any]] = []
+    itemId = str(entities.get("item", "") or _item(query) or "requestedItem")
+    used = "used" in query.lower() or "second hand" in query.lower()
+    budgetUsd = float(budget.get("usd", 0.0) or 0.0)
+    for index, observation in enumerate(observations, start=1):
+        if not observation.get("ok"):
+            continue
+        defaultCurrency = _sourceCurrency(str(observation.get("source", "") or ""), str(entities.get("country", "") or ""))
+        filteredCount = 0
+        listings = observation.get("listings", []) if isinstance(observation.get("listings"), list) else []
+        for listingIndex, listing in enumerate(listings, start=1):
+            if not _listingMatches(listing, itemId, query):
+                continue
+            text = " ".join(str(listing.get(key, "") or "") for key in ("title", "priceText", "textSample"))
+            quotes = _priceQuotes(str(listing.get("priceText", "") or text), defaultCurrency, fxRates)
+            if not quotes:
+                continue
+            offerQuote = min(quotes, key=lambda item: item["usd"])
+            listedQuote = max(quotes, key=lambda item: item["usd"])
+            offer = float(offerQuote["usd"])
+            listed = float(listedQuote["usd"])
+            if listed <= offer:
+                listed = offer
+            if budgetUsd > 0 and offer > budgetUsd:
+                filteredCount += 1
+                continue
+            sourceUrl = str(listing.get("url", "") or observation.get("url", "") or "")
+            sourceKey = "|".join(
+                [
+                    sourceUrl,
+                    str(listingIndex),
+                    str(listing.get("title", "") or ""),
+                    str(listing.get("priceText", "") or ""),
+                    str(offerQuote.get("currency", "")),
+                    str(offerQuote.get("amount", "")),
+                ]
+            )
+            digest = hashlib.sha256(sourceKey.encode("utf-8")).hexdigest()[:12]
+            offers.append(
+                {
+                    "sourceId": f"browserSource_{digest}",
+                    "itemId": itemId,
+                    "listUsd": round(listed, 2),
+                    "offerUsd": round(offer, 2),
+                    "feesUsd": 0.0,
+                    "stock": 1,
+                    "meta": {
+                        "condition": "used" if used else "unknown",
+                        "reader": "browserReader",
+                        "sourceUrl": sourceUrl,
+                        "listingIndex": listingIndex,
+                        "source": str(observation.get("source", "") or ""),
+                        "listingTitle": str(listing.get("title", "") or "")[:220],
+                        "price": {
+                            "amount": round(float(offerQuote["amount"]), 2),
+                            "currency": offerQuote["currency"],
+                            "usd": round(offer, 2),
+                            "fxRate": offerQuote["rate"],
+                        },
+                        "budget": budget,
+                        "sourceBound": True,
+                    },
+                }
+            )
+        if filteredCount:
+            observation["filteredListingCount"] = int(observation.get("filteredListingCount", 0) or 0) + filteredCount
+        if listings:
+            continue
+        if str(observation.get("source", "") or "") != "clientUrl":
+            continue
+        text = " ".join(
+            [
+                str(observation.get("title", "") or ""),
+                " ".join(str(item) for item in observation.get("snippets", []) if item),
+                str(observation.get("textSample", "") or ""),
+            ]
+        )
+        quotes = _priceQuotes(text, defaultCurrency, fxRates)
+        if not quotes:
+            continue
+        offerQuote = min(quotes, key=lambda item: item["usd"])
+        listedQuote = max(quotes, key=lambda item: item["usd"])
+        offer = float(offerQuote["usd"])
+        listed = float(listedQuote["usd"])
+        if listed <= offer:
+            listed = offer
+        if budgetUsd > 0 and offer > budgetUsd:
+            observation["filteredListingCount"] = int(observation.get("filteredListingCount", 0) or 0) + 1
+            continue
+        fallbackKey = "|".join([str(observation.get("url", f"source_{index}") or f"source_{index}"), str(index), str(offerQuote.get("currency", "")), str(offerQuote.get("amount", ""))])
+        digest = hashlib.sha256(fallbackKey.encode("utf-8")).hexdigest()[:12]
+        offers.append(
+            {
+                "sourceId": f"browserSource_{digest}",
+                "itemId": itemId,
+                "listUsd": round(listed, 2),
+                "offerUsd": round(offer, 2),
+                "feesUsd": 0.0,
+                "stock": 1 if re.search(r"\b(?:available|in stock|stock|listing)\b", text.lower()) else 0,
+                "meta": {
+                    "condition": "used" if used else "unknown",
+                    "reader": "browserReader",
+                    "source": str(observation.get("source", "") or ""),
+                    "listingTitle": str(observation.get("title", "") or "")[:220],
+                    "sourceUrl": str(observation.get("url", "") or ""),
+                    "price": {
+                        "amount": round(float(offerQuote["amount"]), 2),
+                        "currency": offerQuote["currency"],
+                        "usd": round(offer, 2),
+                        "fxRate": offerQuote["rate"],
+                    },
+                    "budget": budget,
+                    "sourceBound": True,
+                },
+            }
+        )
+    return offers[:10]
+
+
+def _listingMatches(listing: dict[str, Any], itemId: str, query: str) -> bool:
+    text = " ".join(str(listing.get(key, "") or "") for key in ("title", "textSample")).lower()
+    compact = re.sub(r"[^a-z0-9]+", "", text)
+    if itemId and itemId != "requestedItem":
+        itemCompact = re.sub(r"[^a-z0-9]+", "", itemId.lower())
+        if itemCompact and itemCompact in compact:
+            return True
+    tokens = [
+        token
+        for token in re.findall(r"[a-z0-9]+", query.lower())
+        if len(token) > 2 and token not in {"buy", "used", "less", "than", "under", "dollar", "usd", "best", "find"}
+    ]
+    return bool(tokens and any(token in text for token in tokens[:6]))
+
+
+def _priceQuotes(text: str, defaultCurrency: str, fxRates: dict[str, float]) -> list[dict[str, Any]]:
+    raw = re.sub(r"\s+", " ", str(text or "")).strip()
+    if not raw:
+        return []
+    amountPattern = r"[0-9][0-9\s,.]*(?:[,.][0-9]{1,2})?"
+    tokenPattern = r"USD|SEK|NGN|NOK|EUR|GBP|dollars?|usd|sek|ngn|kr|krona|naira|\$|€|£|₦"
+    matches: list[tuple[str, str]] = []
+    for token, amount in re.findall(rf"({tokenPattern})\s*({amountPattern})", raw, flags=re.IGNORECASE):
+        matches.append((amount, token))
+    for amount, token in re.findall(rf"({amountPattern})\s*({tokenPattern})", raw, flags=re.IGNORECASE):
+        matches.append((amount, token))
+    quotes = []
+    seen = set()
+    for amountRaw, token in matches:
+        amount = _parseAmount(amountRaw)
+        currency = _currencyFromToken(token, defaultCurrency)
+        if amount <= 0 or currency not in fxRates:
+            continue
+        key = (currency, round(amount, 2))
+        if key in seen:
+            continue
+        seen.add(key)
+        rate = float(fxRates.get(currency, 0.0) or 0.0)
+        usd = _toUsd(amount, currency, fxRates)
+        if usd <= 0 or usd > 1_000_000:
+            continue
+        quotes.append({"amount": amount, "currency": currency, "usd": round(usd, 2), "rate": rate})
+    return quotes[:12]
+
+
+def _parseAmount(value: str) -> float:
+    clean = re.sub(r"\s+", "", str(value or ""))
+    if "," in clean and "." in clean:
+        if clean.rfind(",") > clean.rfind("."):
+            clean = clean.replace(".", "").replace(",", ".")
+        else:
+            clean = clean.replace(",", "")
+    elif "," in clean:
+        parts = clean.split(",")
+        clean = "".join(parts) if len(parts[-1]) == 3 else ".".join(parts)
+    elif "." in clean:
+        parts = clean.split(".")
+        clean = "".join(parts) if len(parts[-1]) == 3 and len(parts) > 1 else clean
+    try:
+        return float(clean)
+    except Exception:
+        return 0.0
+
+
+def _currencyFromToken(token: str, defaultCurrency: str) -> str:
+    lowered = str(token or "").strip().lower()
+    if lowered in {"$", "usd", "dollar", "dollars"}:
+        return "USD"
+    if lowered in {"sek", "kr", "krona"}:
+        return "SEK"
+    if lowered in {"ngn", "₦", "naira"}:
+        return "NGN"
+    if lowered == "eur" or lowered == "€":
+        return "EUR"
+    if lowered == "gbp" or lowered == "£":
+        return "GBP"
+    return defaultCurrency.upper() or "USD"
+
+
+def _toUsd(amount: float, currency: str, fxRates: dict[str, float]) -> float:
+    currency = currency.upper() or "USD"
+    rate = float(fxRates.get(currency, 0.0) or 0.0)
+    if currency == "USD":
+        return amount
+    if rate <= 0:
+        return 0.0
+    return amount / rate
+
+
+def _sourceCurrency(source: str, country: str) -> str:
+    source = source.lower()
+    country = country.lower()
+    if source in {"blocket", "tradera", "hemnet"} or country == "se":
+        return "SEK"
+    if source in {"jumia", "konga", "jiji", "propertypro"} or country == "ng":
+        return "NGN"
+    return "USD"
+
+
+def _item(query: str) -> str:
+    serviceEntity = _serviceEntity(query, {})
+    if _isLocalServiceQuery(query) and serviceEntity:
+        return serviceEntity
+    match = re.search(r"\b(i\s*phone\s*\d+|iphone\s*\d+|tv|laptop|car|apartment|house|property|mechanic|plumber|electrician|repair|garage|workshop)\b", query, re.IGNORECASE)
+    if match:
+        return re.sub(r"\s+", "", match.group(1).lower())
+    subject = re.search(
+        r"\b(?:buy|find|get|need|locate|search(?: for)?|shop(?: for)?|source)\s+(?:a|an|the|my|aa)?\s*(.+?)(?:\s+(?:under|less than|below|budget|for|within)\b|\s+(?:in|near|around)\s+[A-Z][A-Za-z]+|$)",
+        query,
+        re.IGNORECASE,
+    )
+    if subject:
+        clean = re.sub(r"\b(?:used|best|cheap|affordable|new)\b", " ", subject.group(1), flags=re.IGNORECASE)
+        clean = re.sub(r"[^A-Za-z0-9 ]+", " ", clean)
+        clean = re.sub(r"\s+", " ", clean).strip().lower()
+        if clean:
+            return clean[:80]
+    return ""
+
+
+def _budget(query: str, payload: dict[str, Any]) -> float:
+    return float(_budgetContext(query, payload, _fxRates(payload)).get("usd", 0.0) or 0.0)
+
+
+def _budgetContext(query: str, payload: dict[str, Any], fxRates: dict[str, float]) -> dict[str, Any]:
+    raw = payload.get("budget", payload.get("maxSpend", 0))
+    payloadCurrency = str(payload.get("currency", payload.get("budgetCurrency", "")) or "").upper()
+    if isinstance(raw, dict):
+        amount = _parseAmount(str(raw.get("amount", raw.get("value", 0)) or "0"))
+        currency = str(raw.get("currency", payloadCurrency or "USD") or "USD").upper()
+        usd = _toUsd(amount, currency, fxRates)
+        return _budgetMap(amount, currency, usd, fxRates)
+    try:
+        if raw:
+            amount = float(raw)
+            currency = payloadCurrency or _budgetCurrency(query, payload) or "USD"
+            usd = _toUsd(amount, currency, fxRates)
+            return _budgetMap(amount, currency, usd, fxRates)
+    except Exception:
+        pass
+    patterns = (
+        r"(?:under|less than|below|budget|for)\s*(?P<prefix>\$|USD|SEK|NGN|₦)?\s*(?P<amount>[0-9][0-9\s,.]*(?:[,.][0-9]{1,2})?)\s*(?P<suffix>dollars?|usd|sek|kr|krona|ngn|naira)?",
+        r"(?P<prefix>\$|USD|SEK|NGN|₦)\s*(?P<amount>[0-9][0-9\s,.]*(?:[,.][0-9]{1,2})?)",
+        r"\b(?P<amount>[0-9][0-9\s,.]*(?:[,.][0-9]{1,2})?)\s*(?P<suffix>dollars?|usd|sek|kr|krona|ngn|naira)\b",
+    )
+    for pattern in patterns:
+        match = re.search(pattern, query, re.IGNORECASE)
+        if not match:
+            continue
+        amount = _parseAmount(match.group("amount"))
+        token = match.groupdict().get("prefix") or match.groupdict().get("suffix") or payloadCurrency or "USD"
+        currency = _currencyFromToken(token, payloadCurrency or "USD")
+        usd = _toUsd(amount, currency, fxRates)
+        return _budgetMap(amount, currency, usd, fxRates)
+    return _budgetMap(0.0, payloadCurrency or _budgetCurrency(query, payload) or "USD", 0.0, fxRates)
+
+
+def _budgetCurrency(query: str, payload: dict[str, Any]) -> str:
+    explicit = str(payload.get("currency", payload.get("budgetCurrency", "")) or "").upper()
+    if explicit:
+        return explicit
+    lowered = query.lower()
+    if "$" in query or "usd" in lowered or "dollar" in lowered:
+        return "USD"
+    if "₦" in query or "ngn" in lowered or "naira" in lowered:
+        return "NGN"
+    if re.search(r"\b(?:sek|kr|krona)\b", lowered):
+        return "SEK"
+    return "USD"
+
+
+def _budgetMap(amount: float, currency: str, usd: float, fxRates: dict[str, float]) -> dict[str, Any]:
+    currency = currency.upper() or "USD"
+    nativeMax = amount
+    return {
+        "amount": round(amount, 2),
+        "currency": currency,
+        "usd": round(usd, 2),
+        "fxRate": float(fxRates.get(currency, 1.0) or 1.0),
+        "nativeMax": round(nativeMax, 2),
+    }
+
+
+def _fxRates(payload: dict[str, Any]) -> dict[str, float]:
+    rates = {key: float(value) for key, value in DEFAULT_FX_RATES.items()}
+    raw = payload.get("fxRates", payload.get("exchangeRates", {}))
+    if isinstance(raw, dict):
+        for key, value in raw.items():
+            try:
+                rate = float(value)
+            except Exception:
+                continue
+            if rate <= 0:
+                continue
+            normalized = str(key).upper().replace("USD_TO_", "").replace("USD_", "")
+            if normalized in {"USD", "SEK", "NGN", "EUR", "GBP", "NOK"}:
+                rates[normalized] = rate
+    return rates
+
+
+def _target(query: str) -> str:
+    domainMerchant = re.search(r"\b(?:to|from|with|at)\s*([A-Z]?[A-Za-z0-9-]+\.(?:se|com|net|org|io|co|ng|uk))\b", query, re.IGNORECASE)
+    if domainMerchant:
+        return domainMerchant.group(1).strip()
+    match = re.search(r"\bfrom\s+([A-Z][A-Za-z0-9.& -]{2,40})", query)
+    return match.group(1).strip() if match else ""
+
+
+def _phone(query: str, payload: dict[str, Any]) -> str:
+    raw = str(payload.get("phone", "") or "")
+    if raw:
+        return raw
+    match = re.search(r"\+?\d[\d\s().-]{7,}\d", query)
+    return match.group(0).strip() if match else ""
+
+
+def _email(query: str) -> str:
+    match = re.search(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", query, flags=re.IGNORECASE)
+    return match.group(0) if match else ""
+
+
+def _market(query: str) -> str:
+    lowered = query.lower()
+    if _isLocalServiceQuery(query):
+        return "localService"
+    if any(token in lowered for token in ("property", "apartment", "house", "rent", "buy home")):
+        return "property"
+    if any(token in lowered for token in ("buy", "shop", "shopping", "iphone", "used", "dollar")):
+        return "shopping"
+    return ""
+
+
+def _country(query: str, payload: dict[str, Any]) -> str:
+    raw = " ".join(
+        str(payload.get(key, "") or "")
+        for key in ("country", "region", "locale", "market", "location")
+    ).lower()
+    lowered = f"{query.lower()} {raw}"
+    if any(token in lowered for token in ("sweden", "swedish", "stockholm", "goteborg", "gothenburg", "malmo", "backebol", "power.se", " se ", "sv-se")):
+        return "se"
+    if any(token in lowered for token in ("nigeria", "lagos", "abuja", "naira", "ngn", " ng ", "en-ng")):
+        return "ng"
+    if any(token in lowered for token in ("united kingdom", "england", "london", " uk ", "en-gb")):
+        return "uk"
+    if any(token in lowered for token in ("united states", "america", "usa", " us ", "en-us")):
+        return "us"
+    compact = raw.replace("_", "-")
+    if compact in {"se", "sv-se"}:
+        return "se"
+    if compact in {"ng", "en-ng"}:
+        return "ng"
+    if compact in {"uk", "gb", "en-gb"}:
+        return "uk"
+    if compact in {"us", "usa", "en-us"}:
+        return "us"
+    return ""
+
+
+def _region(query: str, payload: dict[str, Any]) -> str:
+    country = _country(query, payload)
+    return country.upper() if country else str(payload.get("region", "") or "")
+
+
+def _redact(text: str) -> str:
+    masked = re.sub(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", "[email]", str(text or ""), flags=re.IGNORECASE)
+    return re.sub(r"\+?\b(?:\d[\s().-]?){8,15}\d\b", "[phone]", masked)