patchr 0.1.0__py3-none-any.whl

picux/orchestrator/engine.py

@@ -0,0 +1,2840 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+from typing import Any
+
+from picux.core import ProtocolTaskStatus
+
+
+class PicuxMultiAgentOrchestrator:
+    """Core Picux multi-agent orchestrator used by API, SDK, and test clients."""
+
+    domains = {"hunt", "bridge", "resolve", "proxy", "pay"}
+
+    def __init__(self, host: Any) -> None:
+        self.host = host
+
+    def run(self, payload: dict[str, Any], onEvent: Any | None = None) -> dict[str, Any]:
+        host = self.host
+        resumeAction = self._followUpAction(payload)
+        request = str(payload.get("request", payload.get("goal", payload.get("query", ""))) or "").strip()
+        requestedConversationId = self._conversationId(payload)
+        if not resumeAction and requestedConversationId and self._hasConversationState(host, requestedConversationId):
+            resumeAction = self._followUpTextAction(request)
+        if not request:
+            request = self._resumeRequestLabel(resumeAction, payload) if resumeAction else "Find my best-fit options and return an auditable Picux proof card."
+
+        route = self._route(request, payload)
+        start = time.time()
+        trace: list[dict[str, Any]] = []
+        agentConversation = [f"[User] {request}"]
+        clientId = str(payload.get("clientId", payload.get("userId", "externalClient")) or "externalClient")
+        channel = str(payload.get("channel", "api") or "api")
+        metadata = payload.get("metadata", {}) if isinstance(payload.get("metadata"), dict) else {}
+
+        def stream(kind: str, data: dict[str, Any]) -> None:
+            if onEvent is None:
+                return
+            try:
+                onEvent({"type": kind, **data})
+            except Exception:
+                return
+
+        def event(phase: str, name: str, status: str, msg: str, data: dict[str, Any] | None = None) -> None:
+            traceEvent = {
+                "seq": len(trace) + 1,
+                "phase": phase,
+                "name": name,
+                "status": status,
+                "msg": msg,
+                "elapsedMs": int((time.time() - start) * 1000),
+                "data": data or {},
+            }
+            trace.append(traceEvent)
+            stream("trace", {"event": traceEvent})
+
+        if resumeAction:
+            route = self._resumeRoute(resumeAction)
+            nlp = host.tools.nlp({"request": request, "context": payload.get("context", {}), "taskId": requestedConversationId})
+            nlp = {
+                **nlp,
+                "isFollowUp": True,
+                "route": route,
+                "followUp": {
+                    "action": resumeAction,
+                    "conversationId": requestedConversationId,
+                    "itemId": self._selectedItemId(payload),
+                },
+            }
+            toolResults = {"nlpTool": nlp}
+            event(
+                "tools",
+                "nlpTool",
+                "followUp",
+                "NLPTool classified this payload as a conversation resume request.",
+                {"intent": nlp.get("intent", {}), "route": route, "isFollowUp": True, "followUp": nlp["followUp"]},
+            )
+            return self._runResume(
+                payload=payload,
+                request=request,
+                clientId=clientId,
+                channel=channel,
+                metadata=metadata,
+                route=route,
+                toolResults=toolResults,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+            )
+
+        nlp = host.tools.nlp({"request": request, "context": payload.get("context", {}), "taskId": payload.get("taskId", "")})
+        route = [item for item in nlp.get("route", []) if item in self.domains] or route
+        toolResults: dict[str, Any] = {"nlpTool": nlp}
+        event(
+            "tools",
+            "nlpTool",
+            "classified",
+            "NLPTool classified the user request and selected the orchestration route.",
+            {"intent": nlp.get("intent", {}), "route": route, "isFollowUp": nlp.get("isFollowUp", False)},
+        )
+
+        taskResult = host.createTask(
+            {
+                "userId": clientId,
+                "goal": request,
+                "domain": route[0] if route else "hunt",
+                "channel": channel,
+                "inData": {"request": request, "route": route},
+                "meta": {**metadata, "clientId": clientId, "channel": channel, "conversationId": requestedConversationId},
+            }
+        )
+        task = taskResult.get("task", {})
+        taskId = str(task.get("taskId", "") or self._stableId("task", {"request": request, "route": route}))
+        conversationId = requestedConversationId or taskId
+        if taskId:
+            nextMeta = {**(task.get("meta", {}) if isinstance(task.get("meta"), dict) else {}), "clientId": clientId, "channel": channel, "conversationId": conversationId}
+            savedTask = host.taskBook.updateTask(taskId, {"meta": nextMeta})
+            if savedTask.get("ok"):
+                task = savedTask["task"]
+        event("orchestrator", "taskCreate", "created", "Picux task created from client input.", {"taskId": taskId, "clientId": clientId, "route": route})
+
+        results: dict[str, Any] = {"tools": toolResults}
+        selectedVendor = ""
+        selectedAmount = 0.0
+        mandate: dict[str, Any] = {}
+        proxyCreated = False
+        localServiceFlow = False
+        localServiceContacts: dict[str, dict[str, Any]] = {}
+
+        index = 0
+        while index < len(route):
+            domain = route[index]
+            if domain == "hunt":
+                if self._isLocalServiceRequest(request, payload, nlp):
+                    localServiceFlow = True
+                    mapResult = self._verifiedLocalServiceMapResult(host, request, payload, nlp) or host.tools.searchMap(
+                        {
+                            "request": request,
+                            "entities": nlp.get("entities", {}),
+                            "allowNetwork": payload.get("allowNetwork", False),
+                            "places": payload.get("places", payload.get("mapResults", [])),
+                            "entity": payload.get("entity", payload.get("service", "")),
+                            "location": payload.get("location", metadata.get("location", "")),
+                            "radiusKm": payload.get("radiusKm", payload.get("distanceKm", "")),
+                            "googlePlacesApiKey": payload.get("googlePlacesApiKey", metadata.get("googlePlacesApiKey", "")),
+                            "googleMapsApiKey": payload.get("googleMapsApiKey", metadata.get("googleMapsApiKey", "")),
+                            "googlePlacesBaseUrl": payload.get("googlePlacesBaseUrl", metadata.get("googlePlacesBaseUrl", "")),
+                        }
+                    )
+                    mapOffers = self._placesToOffers(request, mapResult)
+                    localServiceContacts = self._localServiceContactRefs(mapResult, mapOffers)
+                    self._cacheLocalServiceLeads(host, localServiceContacts)
+                    browser = self._mapBrowserTelemetry(mapResult, mapOffers, country=str(payload.get("country", metadata.get("country", "")) or ""))
+                    toolResults["mapTool"] = self._publicMapResult(mapResult)
+                    event(
+                        "tools",
+                        "mapTool",
+                        str(mapResult.get("status", "searched")),
+                        "MapTool searched source-bound local places for HUNT.",
+                        {
+                            "provider": mapResult.get("provider", ""),
+                            "entity": mapResult.get("query", {}).get("entity", "") if isinstance(mapResult.get("query"), dict) else "",
+                            "location": mapResult.get("query", {}).get("location", "") if isinstance(mapResult.get("query"), dict) else "",
+                            "radiusKm": mapResult.get("query", {}).get("radiusKm", 0) if isinstance(mapResult.get("query"), dict) else 0,
+                            "placeCount": len(mapResult.get("places", [])) if isinstance(mapResult.get("places"), list) else 0,
+                            "offerCount": len(mapOffers),
+                            "errors": mapResult.get("errors", []),
+                        },
+                    )
+                else:
+                    browser = host.tools.readBrowser(
+                        {
+                            "request": request,
+                            "entities": nlp.get("entities", {}),
+                            "urls": payload.get("urls", []),
+                            "marketplaces": payload.get("marketplaces", payload.get("sources", [])),
+                            "allowNetwork": payload.get("allowNetwork", False),
+                            "country": payload.get("country", metadata.get("country", "")),
+                            "region": payload.get("region", metadata.get("region", "")),
+                            "locale": payload.get("locale", metadata.get("locale", "")),
+                            "location": payload.get("location", metadata.get("location", "")),
+                            "currency": payload.get("currency", metadata.get("currency", "")),
+                            "budgetCurrency": payload.get("budgetCurrency", metadata.get("budgetCurrency", "")),
+                            "fxRates": payload.get("fxRates", metadata.get("fxRates", {})),
+                        }
+                    )
+                    toolResults["browserReader"] = browser
+                    event(
+                        "tools",
+                        "browserReader",
+                        str(browser.get("status", "read")),
+                        "BrowserReader attempted source-bound discovery without fabricating offers.",
+                        {
+                            "targetCount": len(browser.get("searchTargets", [])),
+                            "observationCount": len(browser.get("observations", [])),
+                            "offerCount": len(browser.get("offers", [])),
+                            "errorCount": len(browser.get("errors", [])),
+                            "adapter": browser.get("adapter", ""),
+                            "rendered": browser.get("rendered", {}),
+                            "marketplaceSet": browser.get("marketplaceSet", {}),
+                            "sourceSearches": [
+                                {
+                                    "source": item.get("source", ""),
+                                    "search": item.get("search", {}),
+                                    "listingCount": item.get("listingCount", 0),
+                                }
+                                for item in browser.get("marketplaceAttempts", [])
+                                if isinstance(item, dict)
+                            ],
+                            "attemptedSources": [item.get("source", "") for item in browser.get("marketplaceAttempts", []) if isinstance(item, dict)],
+                            "failedSources": [item.get("source", "") for item in browser.get("marketplaceAttempts", []) if isinstance(item, dict) and not item.get("ok")],
+                        },
+                    )
+                huntPayload = self._huntPayload(request, payload, taskId=taskId, browser=browser, clientId=clientId, channel=channel)
+                event("hunt", "discover.request", "sent", "HUNT received discovery criteria and source telemetry.", {"endpoint": "/v1/hunt/discover"})
+                hunt = host.huntDiscover(huntPayload)
+                results["hunt"] = hunt
+                selected = hunt.get("selected", {}) if isinstance(hunt.get("selected"), dict) else {}
+                selectedVendor = str(selected.get("sourceId", "") or "")
+                selectedAmount = float(selected.get("netUsd", 0.0) or 0.0)
+                status = "selected" if hunt.get("ok") else "needsSources"
+                msg = f"HUNT selected {selectedVendor}." if selectedVendor else "HUNT could not rank options without source-bound offer telemetry."
+                sourceResponse = hunt.get("sourceResponse", {}) if isinstance(hunt.get("sourceResponse"), dict) else {}
+                event("hunt", "discover.response", status, msg, {"selected": selected, "candidateCount": len(hunt.get("candidates", [])), "sourceResponse": sourceResponse})
+                huntStream = hunt.get("stream", []) if isinstance(hunt.get("stream"), list) else []
+                aggregate = hunt.get("sourceAggregate", {}) if isinstance(hunt.get("sourceAggregate"), dict) else {}
+                if huntStream:
+                    event(
+                        "hunt",
+                        "sourceAggregate.stream",
+                        "returned",
+                        "HUNT streamed aggregated source and result events back to the orchestrator or handoff source.",
+                        {
+                            "eventCount": len(huntStream),
+                            "aggregateId": aggregate.get("aggregateId", ""),
+                            "delivery": aggregate.get("delivery", {}),
+                            "handoff": hunt.get("handoff", {}),
+                        },
+                    )
+                    for streamEvent in huntStream[:50]:
+                        if isinstance(streamEvent, dict):
+                            stream("domainStream", {"domain": "hunt", "event": streamEvent})
+                agentConversation.append("[Hunt] Collecting signals and ranking...")
+                huntSummary = self._huntConversationSummary(request, hunt)
+                if huntSummary:
+                    agentConversation.append(f"[Hunt] {huntSummary}")
+                    stream("conversation", {"line": agentConversation[-1]})
+                if aggregate:
+                    delivery = aggregate.get("delivery", {}) if isinstance(aggregate.get("delivery"), dict) else {}
+                    agentConversation.append("[Hunt] Sending aggregated result back to source.")
+                    stream("conversation", {"line": agentConversation[-1]})
+                agentConversation.append("[Hunt] Selected the best source-bound match for review." if selectedVendor else "[Hunt] I could not find a source-backed match under your filters yet.")
+                stream("conversation", {"line": agentConversation[-1]})
+                if localServiceFlow and hunt.get("ok"):
+                    self._ensureRouteAfter(route, after="hunt", domains=["bridge", "proxy"])
+            elif domain == "bridge":
+                installed = host._ensureReadyConnectors()
+                localServiceContact = self._selectedLocalServiceContact(results.get("hunt", {}), localServiceContacts)
+                if localServiceContact:
+                    event("bridge", "connectorMatch.request", "sent", "BRIDGE checked client-registered voice connector capability for Proxy availability confirmation.", {"endpoint": "/v1/bridge/connectors/match", "caps": ["voice.call", "call.create", "availability.confirm"]})
+                    bridge = host.connectorBook.matchConnectors({"domain": "bridge", "caps": ["voice.call", "call.create", "availability.confirm"]})
+                    connector = self._selectBridgeConnector(bridge, preferred=("twilioVoice", "whatsapp"))
+                    connectorId = str(connector.get("connectorId", "") or "")
+                    preflight = self._connectorPreflight(host, connectorId, action="call", resource="twilio.calls") if connectorId else {"ok": False, "status": "blocked", "errors": ["missingConnector"]}
+                    publicProvider = self._publicLocalServiceContact(localServiceContact)
+                    bridgeStatus = "ready" if preflight.get("ok") else "needsClientCredentials"
+                    contactPlan = {
+                        "mode": "proxyAvailabilityConfirmation",
+                        "target": publicProvider,
+                        "connectorId": connectorId,
+                        "connectorStatus": bridgeStatus,
+                        "credentialContract": {
+                            "mode": "clientRegisteredBridgeResource",
+                            "registerEndpoint": "/v1/bridge/connectors",
+                            "preflightEndpoint": f"/v1/bridge/connectors/{connectorId or '{connectorId}'}/preflight",
+                            "requiredCaps": ["voice.call", "call.create", "availability.confirm"],
+                            "requiredSecretRefs": ["PICUX_TWILIO_ACCOUNT_SID", "PICUX_TWILIO_AUTH_TOKEN", "PICUX_TWILIO_VOICE_FROM", "PICUX_VOICE_PUBLIC_BASE_URL"],
+                        },
+                    }
+                    bridgePayload = {
+                        "ok": bool(connectorId),
+                        "status": bridgeStatus,
+                        "mode": "clientConnector",
+                        "readyConnectors": installed,
+                        "connectors": bridge,
+                        "preflight": preflight,
+                        "contactPlan": contactPlan,
+                        "handoffs": [{"from": "bridge", "to": "proxy", "connectorId": connectorId, "action": "confirmAvailabilityByVoice", "status": "sent" if connectorId else "missingConnector"}],
+                    }
+                    results["bridge"] = bridgePayload
+                    event(
+                        "bridge",
+                        "connectorMatch.response",
+                        bridgeStatus,
+                        "BRIDGE prepared the voice connector contract for PROXY without exposing provider phone details.",
+                        {"connectorId": connectorId, "connectorCount": bridge.get("count", 0), "preflight": {"ok": preflight.get("ok"), "status": preflight.get("status"), "errors": preflight.get("errors", [])}, "target": publicProvider},
+                    )
+                    event("bridge", "handoff.proxy", "sent" if connectorId else "missingConnector", "BRIDGE handed the local provider contact reference to PROXY for availability confirmation.", {"connectorId": connectorId, "contactRef": publicProvider.get("contactRef", ""), "action": "confirmAvailabilityByVoice"})
+                    agentConversation.append("[Bridge] Preparing a voice connector so Proxy can confirm availability.")
+                else:
+                    event("bridge", "connectorMatch.request", "sent", "BRIDGE checked connector capability for outbound contact.", {"endpoint": "/v1/bridge/connectors/match"})
+                    bridge = host.connectorBook.matchConnectors({"domain": "bridge", "caps": ["contact.write", "messages.send", "voice.call"]})
+                    target = self._target(request, payload)
+                    contactPlan = host.resolve.contactPlan(request={"preferredChannel": self._preferredChannel(request)}, target=target)
+                    bridgePayload: dict[str, Any] = {"connectors": bridge, "contactPlan": contactPlan, "readyConnectors": installed}
+                    resolveResult = results.get("resolve", {}) if isinstance(results.get("resolve"), dict) else {}
+                    claimDraft = resolveResult.get("claimDraft", {}) if isinstance(resolveResult.get("claimDraft"), dict) else {}
+                    recovery = resolveResult.get("recovery", {}) if isinstance(resolveResult.get("recovery"), dict) else {}
+                    if claimDraft:
+                        bridgePayload["claimDraft"] = claimDraft
+                        bridgePayload["handoffs"] = [{"from": "resolve", "to": "bridge", "action": "routeClaimDraft", "status": "sent", "target": contactPlan.get("target", {})}]
+                    if recovery:
+                        bridgePayload["recovery"] = recovery
+                        bridgePayload.setdefault("handoffs", []).append({"from": "resolve", "to": "bridge", "action": "launchRecoveryWorkflow", "status": str(recovery.get("status", "queued") or "queued")})
+                    results["bridge"] = bridgePayload
+                    status = "ready" if bridge.get("count", 0) else "adapterNeutral"
+                    event("bridge", "connectorMatch.response", status, "BRIDGE returned contact routing without binding to a vendor adapter.", {"contactPlan": contactPlan, "connectorCount": bridge.get("count", 0), "hasClaimDraft": bool(claimDraft)})
+                    agentConversation.append("[Bridge] Routing the Resolve claim draft to the right contact channel and connector contract..." if claimDraft else "[Bridge] Finding the right contact channel and connector contract...")
+            elif domain == "resolve":
+                documents = payload.get("attachments", payload.get("documents", []))
+                documents = documents if isinstance(documents, list) else []
+                image = host.tools.readImage({"request": request, "images": payload.get("images", []), "attachments": documents, "documents": documents})
+                if image.get("count", 0):
+                    toolResults["imageReader"] = image
+                    documents = [*documents, *image.get("evidence", [])]
+                    event(
+                        "tools",
+                        "imageReader",
+                        "read",
+                        "ImageReader extracted query-relevant evidence from image attachments.",
+                        {"imageCount": image.get("count", 0), "evidenceCount": len(image.get("evidence", []))},
+                    )
+                event("resolve", "scamTriage.request", "sent", "RESOLVE received claim text and evidence references.", {"endpoint": "/v1/resolve/scamTriage", "documentCount": len(documents)})
+                resolve = host.resolveScamTriage({"claim": request, "text": request, "documents": documents, "attachments": documents, "taskId": taskId})
+                target = self._target(request, payload)
+                if target:
+                    resolve["claimDraft"] = host.resolve.draftClaim(request={"issueType": self._issueType(request), "attachments": documents}, audit={}, target=target)
+                recovery = self._startResolveRecovery(host, request=request, payload=payload, target=target, documents=documents, taskId=taskId, conversationId=conversationId)
+                if recovery:
+                    resolve["recovery"] = recovery
+                    event("resolve", "recovery.queue", str(recovery.get("status", "queued") or "queued"), "RESOLVE launched the recovery workflow and queued Bridge or portal work from the case.", {"recovery": recovery})
+                results["resolve"] = resolve
+                triage = resolve.get("triage", {}) if isinstance(resolve.get("triage"), dict) else {}
+                nextAction = str(triage.get("nextAction", "prepareReviewableRecord") or "prepareReviewableRecord")
+                event("resolve", "scamTriage.response", nextAction, "RESOLVE produced a reviewable evidence map and next action.", {"risk": triage.get("risk", {}), "openQuestions": triage.get("openQuestions", [])})
+                agentConversation.append("[Resolve] Checking risk, evidence, chronology, and safe next action...")
+                escalation = triage.get("escalation", {}) if isinstance(triage.get("escalation"), dict) else {}
+                if escalation.get("recommended"):
+                    event("resolve", "escalation.check", "recommended", "RESOLVE recommended human review; PROXY opens when the request needs follow-up, voice, logistics, or explicit human review.", escalation)
+                if escalation.get("recommended") and "proxy" not in route and self._shouldCreateProxy(request, payload):
+                    insertAt = route.index("bridge") + 1 if "bridge" in route and route.index("bridge") > index else index + 1
+                    route.insert(insertAt, "proxy")
+            elif domain == "proxy":
+                localServiceContact = self._selectedLocalServiceContact(results.get("hunt", {}), localServiceContacts)
+                if localServiceContact:
+                    bridgeResult = results.get("bridge", {}) if isinstance(results.get("bridge"), dict) else {}
+                    publicProvider = self._publicLocalServiceContact(localServiceContact)
+                    contactRef = str(localServiceContact.get("contactRef", publicProvider.get("contactRef", "")) or "")
+                    connectorId = str(bridgeResult.get("contactPlan", {}).get("connectorId", "") if isinstance(bridgeResult.get("contactPlan"), dict) else "")
+                    preflight = bridgeResult.get("preflight", {}) if isinstance(bridgeResult.get("preflight"), dict) else {}
+                    hasPrivateContact = bool(str(localServiceContact.get("phone", "") or ""))
+                    callStatus = "readyToCall" if hasPrivateContact and preflight.get("ok") else ("needsClientCredentials" if connectorId else "missingVoiceConnector")
+                    if not hasPrivateContact:
+                        callStatus = "needsProviderContact"
+                    voiceCall = {
+                        "phoneRef": contactRef,
+                        "status": callStatus,
+                        "connectorId": connectorId,
+                        "prompt": f"Confirm availability for this Picux local service request. Provider: {publicProvider.get('name', '')}. User need: {request}",
+                    }
+                    event("proxy", "mission.request", "sent", "PROXY received the local provider as a callable human/business node.", {"endpoint": "/v1/proxy/missions", "reason": "localServiceAvailability", "contactRef": contactRef, "connectorId": connectorId, "callStatus": callStatus})
+                    proxyStatus, proxy = host.createProxyMission(
+                        {
+                            "taskId": taskId,
+                            "userId": clientId,
+                            "kind": "call",
+                            "reason": "localServiceAvailability",
+                            "task": f"Call {publicProvider.get('name') or 'the selected provider'} to confirm availability.",
+                            "context": {
+                                "missionState": {"route": route, "request": request, "clientId": clientId, "conversationId": conversationId},
+                                "decisionFork": {"options": ["providerAvailable", "providerUnavailable", "requestAnotherProvider"]},
+                                "logisticsBrief": {
+                                    "why": "HUNT found a local service provider; PROXY must confirm real-world availability before presenting the provider as verified.",
+                                    "selectedProvider": publicProvider,
+                                },
+                                "reason": "localServiceAvailability",
+                                "selectedProvider": publicProvider,
+                                "contactRef": contactRef,
+                                "connectorId": connectorId,
+                                "bridgePreflight": {"ok": preflight.get("ok"), "status": preflight.get("status"), "errors": preflight.get("errors", [])},
+                                "availabilityVerification": {"status": callStatus, "providerName": publicProvider.get("name", ""), "contactRef": contactRef},
+                            },
+                            "voiceCall": voiceCall,
+                            "proofReq": ["callTranscript", "availabilityWindow", "mechanicName", "consentRecord"],
+                            "resume": {"conversationId": conversationId, "candidateId": str(publicProvider.get("providerId", "") or contactRef), "action": "proxyOutcome"},
+                        }
+                    )
+                    proxyCreated = proxyStatus < 400 and bool(proxy.get("ok"))
+                    results["proxy"] = proxy
+                    event("proxy", "mission.response", "awaitingProxy" if proxyCreated else "blocked", "PROXY opened the availability-confirmation mission for the selected provider." if proxyCreated else "PROXY mission could not be created.", {"proxyId": proxy.get("proxyId", ""), "status": proxyStatus, "callStatus": callStatus})
+                    agentConversation.append("[Proxy] Taking over the availability call and waiting for the provider's confirmation proof...")
+                else:
+                    resolveResult = results.get("resolve", {}) if isinstance(results.get("resolve"), dict) else {}
+                    bridgeResult = results.get("bridge", {}) if isinstance(results.get("bridge"), dict) else {}
+                    triage = resolveResult.get("triage", {}) if isinstance(resolveResult.get("triage"), dict) else {}
+                    claimDraft = resolveResult.get("claimDraft", {}) if isinstance(resolveResult.get("claimDraft"), dict) else {}
+                    contactPlan = bridgeResult.get("contactPlan", {}) if isinstance(bridgeResult.get("contactPlan"), dict) else {}
+                    proxyReason = "resolveEscalationReview" if resolveResult else "humanReviewOrContact"
+                    event("proxy", "mission.request", "sent", "PROXY received a suspend-resume mission for human review or contact.", {"endpoint": "/v1/proxy/missions", "reason": proxyReason})
+                    proxyStatus, proxy = host.createProxyMission(
+                        {
+                            "taskId": taskId,
+                            "userId": clientId,
+                            "kind": "call" if self._hasPhone(request, payload) else "review",
+                            "reason": proxyReason,
+                            "task": request,
+                            "context": {
+                                "missionState": {"route": route, "request": request, "clientId": clientId},
+                                "decisionFork": {"options": ["continue", "requestMoreEvidence", "stop"]},
+                                "logisticsBrief": {"why": "Human judgment or real-world contact is required before the agent can continue."},
+                                "phone": self._phone(request, payload),
+                                "resolveTriage": triage,
+                                "claimDraft": claimDraft,
+                                "contactPlan": contactPlan,
+                            },
+                            "voiceCall": {"phone": self._phone(request, payload), "prompt": request},
+                        }
+                    )
+                    proxyCreated = proxyStatus < 400 and bool(proxy.get("ok"))
+                    results["proxy"] = proxy
+                    event("proxy", "mission.response", "awaitingProxy" if proxyCreated else "blocked", "PROXY suspended the run until a human outcome is returned." if proxyCreated else "PROXY mission could not be created.", {"proxyId": proxy.get("proxyId", ""), "status": proxyStatus})
+                    agentConversation.append("[Proxy] Human review, voice, chat, or logistics handoff is waiting for completion proof...")
+            elif domain == "pay":
+                amount = selectedAmount or self._budget(request, payload) or 0.0
+                if not selectedVendor and not payload.get("payeeId"):
+                    results["pay"] = {"ok": False, "error": "missingSourceBoundPayee", "reason": "PAY requires a selected source-bound payee or explicit payeeId."}
+                    event("pay", "prepare.blocked", "blocked", "PAY refused to prepare a mandate without a selected source-bound payee.", {"amount": amount})
+                    agentConversation.append("[Pay] Skipped mandate preparation because no source-bound payee was selected.")
+                    index += 1
+                    continue
+                selectedVendor = selectedVendor or str(payload.get("payeeId", "") or "")
+                mandate = host.createMandate(
+                    {
+                        "mandateId": self._stableId("mandate", {"taskId": taskId, "request": request}),
+                        "issuer": {
+                            "entityId": clientId,
+                            "publicKey": str(payload.get("publicKey", "clientPublicKey") or "clientPublicKey"),
+                        },
+                        "constraints": {
+                            "maxSpend": {"amount": self._budget(request, payload) or max(amount, 1.0), "currency": "USD"},
+                            "allowedVendors": [selectedVendor],
+                            "resolveRules": ["sourceBound", "proofBeforeSettlement"],
+                        },
+                        "validUntil": "2099-01-01T00:00:00Z",
+                        "signature": str(payload.get("signature", "clientSignature") or "clientSignature"),
+                    }
+                )
+                escrow = host.createEscrow(
+                    {
+                        "taskId": taskId,
+                        "mandateId": mandate.get("mandateId", ""),
+                        "status": "prepared",
+                        "amount": {"amount": amount, "currency": "USD"},
+                        "request": {"taskId": taskId, "vendorId": selectedVendor, "amount": {"amount": amount, "currency": "USD"}},
+                    }
+                )
+                results["pay"] = {"mandate": mandate, "escrow": escrow}
+                event("pay", "prepare.response", "prepared", "PAY prepared a mandate and escrow boundary; settlement remains proof-gated.", {"mandateId": mandate.get("mandateId", ""), "escrowId": escrow.get("escrow", {}).get("escrowId", "")})
+                agentConversation.append("[Pay] Preparing mandate, settlement boundary, and proof-gated escrow...")
+            index += 1
+
+        status = "awaitingProxy" if proxyCreated else "ready"
+        if results.get("hunt") and not results["hunt"].get("ok"):
+            status = "needsSourceTelemetry"
+        if isinstance(results.get("pay"), dict) and results["pay"].get("ok") is False:
+            status = "blocked"
+        event("orchestrator", "proofPack", "created", "Picux created a portable proof card for the orchestrated run.", {"status": status})
+        proof = host._proofPackForRun(
+            taskId=taskId,
+            domain="orchestrator",
+            title="Picux orchestrated run",
+            summary=f"Picux routed the request through {', '.join(route).upper()} and produced a reviewable case file.",
+            payload={"request": request, "route": route, "results": results, "client": {"clientId": clientId, "channel": channel}},
+            decisions=[{"label": item["name"], "reason": item["status"]} for item in trace if item["phase"] != "orchestrator"],
+            evidenceStatus="sourceBound" if results else "needsEvidence",
+            confidence=0.72 if status == "ready" else 0.58,
+            openQuestions=["awaitingProxyOutcome"] if proxyCreated else ([] if status == "ready" else ["sourceTelemetryRequired"]),
+            escalation={"recommended": proxyCreated or status != "ready", "routeDomain": "proxy" if proxyCreated else "", "reason": status},
+        )
+        agentConversation.append("[Picux] I prepared the result with evidence status, open questions, and next steps.")
+        stream("conversation", {"line": agentConversation[-1]})
+        host.taskBook.updateTask(
+            taskId,
+            {
+                "status": ProtocolTaskStatus.AWAITING_PROXY.value if proxyCreated else (ProtocolTaskStatus.FAILED.value if status in {"blocked", "needsSourceTelemetry"} else ProtocolTaskStatus.COMPLETED.value),
+                "outData": {"conversationId": conversationId, "route": route, "status": status, "results": results, "decisionTree": self._decisionTree(results.get("hunt", {})), "proofPack": proof.get("proofPack", {})},
+            },
+        )
+        return {
+            "ok": True,
+            "scenario": "picuxOrchestrator",
+            "status": status,
+            "conversationId": conversationId,
+            "request": request,
+            "route": route,
+            "task": task,
+            "trace": trace,
+            "agentConversation": agentConversation,
+            "results": results,
+            "decisionTree": self._decisionTree(results.get("hunt", {})),
+            "mandate": mandate.get("mandate", mandate),
+            "receipt": None,
+            "freezeReceipt": None,
+            "proofPack": proof.get("proofPack", {}),
+            "proofCard": proof.get("proofPack", {}).get("proofCard", {}),
+        }
+
+    def _runResume(
+        self,
+        *,
+        payload: dict[str, Any],
+        request: str,
+        clientId: str,
+        channel: str,
+        metadata: dict[str, Any],
+        route: list[str],
+        toolResults: dict[str, Any],
+        trace: list[dict[str, Any]],
+        agentConversation: list[str],
+        event: Any,
+        stream: Any,
+    ) -> dict[str, Any]:
+        host = self.host
+        action = self._followUpAction(payload)
+        conversationId = self._conversationId(payload)
+        selectedItemId = self._selectedItemId(payload)
+        if not conversationId:
+            event("orchestrator", "conversation.load", "missing", "Picux could not resume because conversationId is missing.", {"action": action, "itemId": selectedItemId})
+            return self._resumeFailure(
+                request=request,
+                route=route,
+                status="conversationNotFound",
+                error="missing:conversationId",
+                conversationId="",
+                clientId=clientId,
+                channel=channel,
+                trace=trace,
+                agentConversation=agentConversation,
+                results={"tools": toolResults},
+                event=event,
+                stream=stream,
+            )
+
+        taskLookup = host.taskBook.getTaskByConversationId(conversationId) if hasattr(host.taskBook, "getTaskByConversationId") else host.taskBook.getTask(conversationId)
+        if not taskLookup.get("ok"):
+            event("orchestrator", "conversation.load", "missing", "Picux could not find the conversation state for this follow-up.", {"conversationId": conversationId, "error": taskLookup.get("error", "")})
+            return self._resumeFailure(
+                request=request,
+                route=route,
+                status="conversationNotFound",
+                error=str(taskLookup.get("error", "conversationNotFound") or "conversationNotFound"),
+                conversationId=conversationId,
+                clientId=clientId,
+                channel=channel,
+                trace=trace,
+                agentConversation=agentConversation,
+                results={"tools": toolResults},
+                event=event,
+                stream=stream,
+            )
+
+        task = taskLookup.get("task", {}) if isinstance(taskLookup.get("task"), dict) else {}
+        taskId = str(task.get("taskId", "") or conversationId)
+        priorOut = task.get("outData", {}) if isinstance(task.get("outData"), dict) else {}
+        priorResults = priorOut.get("results", {}) if isinstance(priorOut.get("results"), dict) else {}
+        hunt = priorResults.get("hunt", {}) if isinstance(priorResults.get("hunt"), dict) else {}
+        event("orchestrator", "conversation.load", "loaded", "Picux loaded the previous conversation state.", {"conversationId": conversationId, "taskId": taskId, "action": action})
+        if not hunt:
+            resume = {"action": action, "status": "missingHuntState", "conversationId": conversationId, "requestedItemId": selectedItemId}
+            results = {"tools": toolResults, "hunt": {"ok": False, "error": "missingHuntState", "conversationId": conversationId}}
+            results["resume"] = resume
+            event("hunt", "candidate.validate", "blocked", "HUNT has no previous candidate state to validate.", {"conversationId": conversationId})
+            return self._finalizeResume(
+                task=task,
+                priorOut=priorOut,
+                request=request,
+                conversationId=conversationId,
+                route=["hunt"],
+                status="missingHuntState",
+                ok=False,
+                results=results,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+                taskStatus=ProtocolTaskStatus.PROCESSING.value,
+                evidenceStatus="needsEvidence",
+                confidence=0.35,
+                openQuestions=["initialHuntResultRequired"],
+                escalation={"recommended": True, "routeDomain": "hunt", "reason": "missingHuntState"},
+            )
+
+        if not selectedItemId:
+            selectedItemId = self._selectedItemId(payload, hunt=hunt, request=request)
+
+        candidate = self._candidateById(hunt, selectedItemId)
+        if not candidate:
+            refs = self._candidateRefs(hunt)
+            resume = {
+                "action": action,
+                "status": "invalidCandidate",
+                "conversationId": conversationId,
+                "requestedItemId": selectedItemId,
+                "availableCandidates": refs,
+            }
+            results = {
+                "tools": toolResults,
+                "hunt": {
+                    **hunt,
+                    "resume": resume,
+                },
+                "resume": resume,
+            }
+            event("hunt", "candidate.validate", "invalid", "HUNT rejected the follow-up because the selected item does not belong to this conversation.", {"itemId": selectedItemId, "availableCandidates": refs[:8]})
+            agentConversation.append("[Hunt] I could not match that selected item to the source-bound options in this conversation.")
+            stream("conversation", {"line": agentConversation[-1]})
+            return self._finalizeResume(
+                task=task,
+                priorOut=priorOut,
+                request=request,
+                conversationId=conversationId,
+                route=["hunt"],
+                status="invalidCandidate",
+                ok=False,
+                results=results,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+                taskStatus=ProtocolTaskStatus.PROCESSING.value,
+                evidenceStatus="sourceBound",
+                confidence=0.42,
+                openQuestions=["validCandidateIdRequired"],
+                escalation={"recommended": True, "routeDomain": "hunt", "reason": "invalidCandidate"},
+            )
+
+        candidateRef = self._candidateRef(candidate)
+        event("hunt", "candidate.validate", "valid", "HUNT validated the selected source-bound candidate.", {"conversationId": conversationId, "candidate": candidateRef})
+        agentConversation.append(f"[Hunt] Resumed this conversation and validated {candidateRef.get('title') or candidateRef.get('candidateId')} from {self._displaySource(str(candidateRef.get('source', '') or 'the source'))}.")
+        stream("conversation", {"line": agentConversation[-1]})
+
+        if action == "pass":
+            rejected = self._rejectedCandidateIds(priorOut)
+            if candidateRef["candidateId"] not in rejected:
+                rejected.append(candidateRef["candidateId"])
+            nextCandidate = self._nextCandidateRef(hunt, rejected)
+            resume = {
+                "action": "pass",
+                "status": "candidatePassed",
+                "conversationId": conversationId,
+                "passedCandidate": candidateRef,
+                "nextCandidate": nextCandidate,
+                "rejectedCandidateIds": rejected,
+            }
+            results = {"tools": toolResults, "hunt": {**hunt, "resume": resume}, "resume": resume}
+            if nextCandidate:
+                agentConversation.append(f"[Hunt] You passed on that option. The next source-bound option is {nextCandidate.get('title') or nextCandidate.get('candidateId')}.")
+            else:
+                agentConversation.append("[Hunt] You passed on that option. I do not have another source-bound candidate from the current result set.")
+            stream("conversation", {"line": agentConversation[-1]})
+            return self._finalizeResume(
+                task=task,
+                priorOut=priorOut,
+                request=request,
+                conversationId=conversationId,
+                route=["hunt"],
+                status="candidatePassed",
+                ok=True,
+                results=results,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+                taskStatus=ProtocolTaskStatus.PROCESSING.value,
+                evidenceStatus="sourceBound",
+                confidence=0.68,
+                openQuestions=[] if nextCandidate else ["noMoreSourceBoundOptions"],
+                escalation={"recommended": not bool(nextCandidate), "routeDomain": "hunt" if not nextCandidate else "", "reason": "candidatePassed"},
+            )
+
+        if self._isLocalServiceCandidate(candidateRef):
+            return self._runLocalServiceResume(
+                payload=payload,
+                task=task,
+                priorOut=priorOut,
+                hunt=hunt,
+                candidateRef=candidateRef,
+                request=request,
+                conversationId=conversationId,
+                taskId=taskId,
+                clientId=clientId,
+                channel=channel,
+                toolResults=toolResults,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+            )
+
+        if action == "contact":
+            return self._runCandidateContactResume(
+                payload=payload,
+                task=task,
+                priorOut=priorOut,
+                hunt=hunt,
+                candidateRef=candidateRef,
+                request=request,
+                conversationId=conversationId,
+                taskId=taskId,
+                clientId=clientId,
+                toolResults=toolResults,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+            )
+
+        if action == "refine":
+            resume = {
+                "action": "refine",
+                "status": "NEEDS_INPUT",
+                "conversationId": conversationId,
+                "selectedCandidate": candidateRef,
+                "requestedKeys": ["refinement"],
+            }
+            results = {"tools": toolResults, "hunt": {**hunt, "resume": resume}, "resume": resume}
+            event("hunt", "refine.awaitingInput", "NEEDS_INPUT", "HUNT needs the updated filter, budget, or constraint for this follow-up.", {"candidate": candidateRef})
+            agentConversation.append("[Hunt] Tell me what to change in the search: budget, location, source, condition, or another filter.")
+            stream("conversation", {"line": agentConversation[-1]})
+            return self._finalizeResume(
+                task=task,
+                priorOut=priorOut,
+                request=request,
+                conversationId=conversationId,
+                route=["hunt"],
+                status="NEEDS_INPUT",
+                ok=True,
+                results=results,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+                taskStatus=ProtocolTaskStatus.PROCESSING.value,
+                evidenceStatus="sourceBound",
+                confidence=0.62,
+                openQuestions=["refinement"],
+                escalation={"recommended": False, "routeDomain": "hunt", "reason": "awaitingRefinement"},
+            )
+
+        purchaseInputs = self._purchaseInputs(payload)
+        missingContactKeys = self._missingContactKeys(purchaseInputs)
+        missingPaymentKeys = [] if missingContactKeys else self._missingPaymentKeys(purchaseInputs)
+        missingKeys = missingContactKeys or missingPaymentKeys
+        resumeStatus = "NEEDS_INPUT" if missingContactKeys else ("NEEDS_PAYMENT_INFO" if missingPaymentKeys else "purchasePrepared")
+        purchaseIntent = self._purchaseIntent(conversationId, taskId, candidateRef, purchaseInputs, missingKeys, resumeStatus)
+        resume = {
+            "action": "buy",
+            "status": resumeStatus,
+            "conversationId": conversationId,
+            "selectedCandidate": candidateRef,
+            "purchaseIntent": purchaseIntent,
+            "requestedKeys": missingKeys,
+            "resumeToken": self._stableId("resume", {"conversationId": conversationId, "candidateId": candidateRef["candidateId"], "action": "buy"}),
+        }
+        results = {
+            "tools": toolResults,
+            "hunt": {**hunt, "resume": {"action": "buy", "status": "candidateValidated", "selectedCandidate": candidateRef}},
+            "purchaseIntent": purchaseIntent,
+        }
+        bridgeRoute = ["hunt", "bridge", "pay"]
+        if missingContactKeys:
+            bridge = self._bridgeNeedsInput(candidateRef, missingKeys)
+            pay = {
+                "ok": False,
+                "status": "AWAITING_INPUT",
+                "requestedKeys": [],
+                "supportedPaymentMethods": self._supportedPaymentMethods(),
+                "paymentSchema": self._paymentSchema(),
+                "settlementGate": {"status": "locked", "reason": "missingContactOrLogisticsInput", "proofRequired": True},
+            }
+            results["bridge"] = bridge
+            results["pay"] = pay
+            results["resume"] = resume
+            event("bridge", "checkout.prepare", "NEEDS_INPUT", "BRIDGE paused checkout routing until the client supplies required purchase inputs.", {"requestedKeys": missingKeys, "candidate": candidateRef})
+            event("pay", "prepare.awaitingInput", "AWAITING_INPUT", "PAY discovered supported payment methods but is waiting for contact and logistics input before collecting payment data.", {"supportedPaymentMethods": self._supportedPaymentMethods()})
+            agentConversation.append(f"[Bridge] I need {', '.join(missingKeys)} before I can prepare checkout routing.")
+            stream("conversation", {"line": agentConversation[-1]})
+            agentConversation.append("[Pay] I found the supported payment methods, but payment collection waits until the required contact and logistics input is complete.")
+            stream("conversation", {"line": agentConversation[-1]})
+            return self._finalizeResume(
+                task=task,
+                priorOut=priorOut,
+                request=request,
+                conversationId=conversationId,
+                route=bridgeRoute,
+                status="NEEDS_INPUT",
+                ok=True,
+                results=results,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+                taskStatus=ProtocolTaskStatus.PROCESSING.value,
+                evidenceStatus="sourceBound",
+                confidence=0.64,
+                openQuestions=missingKeys,
+                escalation={"recommended": True, "routeDomain": "bridge", "reason": "missingPurchaseInput"},
+            )
+
+        if missingPaymentKeys:
+            bridge = {
+                "ok": True,
+                "status": "inputReady",
+                "mode": "adapterNeutral",
+                "checkout": {
+                    "action": "preparePaymentInfo",
+                    "source": candidateRef.get("source", ""),
+                    "url": candidateRef.get("url", ""),
+                    "candidateId": candidateRef.get("candidateId", ""),
+                },
+            }
+            pay = {
+                "ok": False,
+                "status": "NEEDS_PAYMENT_INFO",
+                "requestedKeys": missingPaymentKeys,
+                "supportedPaymentMethods": self._supportedPaymentMethods(),
+                "paymentSchema": self._paymentSchema(),
+                "settlementGate": {"status": "locked", "reason": "missingPaymentInfo", "proofRequired": True},
+            }
+            results["bridge"] = bridge
+            results["pay"] = pay
+            results["resume"] = resume
+            event("bridge", "checkout.prepare", "inputReady", "BRIDGE has enough contact and logistics input to prepare checkout routing.", {"candidate": candidateRef})
+            event("pay", "prepare.needsPaymentInfo", "NEEDS_PAYMENT_INFO", "PAY discovered supported payment methods and requested method-specific payment information.", {"requestedKeys": missingPaymentKeys, "supportedPaymentMethods": self._supportedPaymentMethods()})
+            agentConversation.append("[Bridge] Contact and logistics input is ready for checkout routing.")
+            stream("conversation", {"line": agentConversation[-1]})
+            agentConversation.append("[Pay] Choose a supported payment method and provide the method-specific payment details.")
+            stream("conversation", {"line": agentConversation[-1]})
+            return self._finalizeResume(
+                task=task,
+                priorOut=priorOut,
+                request=request,
+                conversationId=conversationId,
+                route=bridgeRoute,
+                status="NEEDS_PAYMENT_INFO",
+                ok=True,
+                results=results,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+                taskStatus=ProtocolTaskStatus.PROCESSING.value,
+                evidenceStatus="sourceBound",
+                confidence=0.68,
+                openQuestions=missingPaymentKeys,
+                escalation={"recommended": True, "routeDomain": "pay", "reason": "missingPaymentInfo"},
+            )
+
+        installed = host._ensureReadyConnectors()
+        checkoutConnectors = host.connectorBook.matchConnectors({"domain": "bridge", "caps": ["marketplace.checkout", "browser.checkout", "purchase.execute"]})
+        connectorRecords = checkoutConnectors.get("connectors", []) if isinstance(checkoutConnectors.get("connectors"), list) else []
+        checkoutConnector = connectorRecords[0] if connectorRecords and isinstance(connectorRecords[0], dict) else {}
+        checkoutConnectorId = str(checkoutConnector.get("connectorId", "") or "")
+        bridge = {
+            "ok": True,
+            "status": "purchaseAttempting",
+            "mode": "browserCheckout",
+            "readyConnectors": installed,
+            "connectors": checkoutConnectors,
+            "checkout": {
+                "action": "browserPurchase",
+                "connectorId": checkoutConnectorId,
+                "source": candidateRef.get("source", ""),
+                "url": candidateRef.get("url", ""),
+                "candidateId": candidateRef["candidateId"],
+                "note": "Picux is attempting source-bound checkout through the browser tool and will fail closed if purchase confirmation is not observed.",
+            },
+            "handoffs": [
+                {"from": "bridge", "to": "pay", "action": "prepareMandateEscrow", "status": "sent"},
+                {"from": "bridge", "to": "browserCheckout", "connectorId": checkoutConnectorId, "action": "executePurchase", "status": "sent" if checkoutConnectorId else "blocked"},
+            ],
+        }
+        event("bridge", "checkout.connectorMatch", "matched" if checkoutConnectorId else "missingConnector", "BRIDGE matched a checkout connector for marketplace purchase execution." if checkoutConnectorId else "BRIDGE could not find a checkout connector for marketplace purchase execution.", {"connectorId": checkoutConnectorId, "connectorCount": checkoutConnectors.get("count", 0), "caps": ["marketplace.checkout", "browser.checkout", "purchase.execute"]})
+        event("bridge", "handoff.pay", "sent", "BRIDGE handed the purchase intent to PAY for mandate and escrow preparation.", {"target": "pay", "purchaseIntentId": purchaseIntent["intentId"], "candidateId": candidateRef["candidateId"]})
+        event("bridge", "checkout.prepare", "purchaseAttempting", "BRIDGE prepared the source-bound browser checkout attempt.", {"connectorCount": checkoutConnectors.get("count", 0), "connectorId": checkoutConnectorId, "candidate": candidateRef})
+        amount = float(candidateRef.get("netUsd", 0.0) or 0.0)
+        vendorId = str(candidateRef.get("sourceId", "") or candidateRef["candidateId"])
+        event("pay", "prepare.request", "received", "PAY received the purchase intent from BRIDGE and is preparing mandate plus escrow.", {"purchaseIntentId": purchaseIntent["intentId"], "amount": amount, "vendorId": vendorId})
+        mandate = host.createMandate(
+            {
+                "mandateId": self._stableId("mandate", {"conversationId": conversationId, "candidateId": candidateRef["candidateId"], "intentId": purchaseIntent["intentId"]}),
+                "issuer": {
+                    "entityId": clientId,
+                    "publicKey": str(payload.get("publicKey", "clientPublicKey") or "clientPublicKey"),
+                },
+                "constraints": {
+                    "maxSpend": {"amount": max(amount, 1.0), "currency": "USD"},
+                    "allowedVendors": [vendorId],
+                    "resolveRules": ["sourceBound", "purchaseIntent", "verifiedCompletionProof", "userConfirmedPurchase"],
+                },
+                "validUntil": "2099-01-01T00:00:00Z",
+                "signature": str(payload.get("signature", "clientSignature") or "clientSignature"),
+                "meta": {"conversationId": conversationId, "purchaseIntentId": purchaseIntent["intentId"]},
+            }
+        )
+        escrow = host.createEscrow(
+            {
+                "taskId": taskId,
+                "mandateId": mandate.get("mandateId", ""),
+                "status": "prepared",
+                "amount": {"amount": amount, "currency": "USD"},
+                "request": {
+                    "taskId": taskId,
+                    "conversationId": conversationId,
+                    "purchaseIntentId": purchaseIntent["intentId"],
+                    "vendorId": vendorId,
+                    "amount": {"amount": amount, "currency": "USD"},
+                },
+            }
+        )
+        pay = {
+            "ok": True,
+            "status": "prepared",
+            "mandate": mandate,
+            "escrow": escrow,
+            "settlementGate": {"status": "locked", "reason": "awaitingVerifiedCompletionProof", "proofRequired": True},
+        }
+        if checkoutConnectorId:
+            event("bridge", "handoff.browserCheckout", "sent", "BRIDGE handed purchase execution to the Browser Checkout connector.", {"connectorId": checkoutConnectorId, "endpoint": checkoutConnector.get("endpoint", ""), "purchaseIntentId": purchaseIntent["intentId"], "candidateId": candidateRef["candidateId"]})
+            checkout = host.tools.checkoutBrowser(
+                {
+                    **self._safePurchaseInputs(purchaseInputs),
+                    "connectorId": checkoutConnectorId,
+                    "url": candidateRef.get("url", ""),
+                    "source": candidateRef.get("source", ""),
+                    "candidateId": candidateRef["candidateId"],
+                    "purchaseIntentId": purchaseIntent["intentId"],
+                    "executePurchase": bool(payload.get("executePurchase", payload.get("allowPurchaseExecution", False))),
+                }
+            )
+        else:
+            checkout = {
+                "ok": False,
+                "tool": "browserCheckout",
+                "status": "blocked",
+                "reason": "bridgeCheckoutConnectorMissing",
+                "message": "Sorry, I am unable to make the purchase due to bridgeCheckoutConnectorMissing.",
+                "candidateId": candidateRef["candidateId"],
+                "source": candidateRef.get("source", ""),
+                "url": candidateRef.get("url", ""),
+                "executePurchase": bool(payload.get("executePurchase", payload.get("allowPurchaseExecution", False))),
+            }
+        toolResults["browserCheckout"] = checkout
+        purchaseOk = bool(checkout.get("ok"))
+        checkoutNeedsInput = self._checkoutNeedsInput(checkout)
+        purchaseStatus = "purchaseCompleted" if purchaseOk else ("NEEDS_INPUT" if checkoutNeedsInput else "purchaseBlocked")
+        purchaseOutcome = {
+            "ok": purchaseOk,
+            "status": "purchased" if purchaseOk else ("needsInput" if checkoutNeedsInput else "blocked"),
+            "message": "Item successfully purchased" if purchaseOk else f"Sorry, I am unable to make the purchase due to {checkout.get('reason', 'purchaseFailed')}.",
+            "reason": str(checkout.get("reason", "") or ""),
+            "checkout": checkout,
+        }
+        payExecution: dict[str, Any] = {}
+        if purchaseOk:
+            payExecution = self._settleCheckoutProof(
+                host,
+                escrow=escrow,
+                purchaseIntent=purchaseIntent,
+                candidateRef=candidateRef,
+                checkout=checkout,
+                event=event,
+            )
+            if payExecution:
+                pay = {**pay, **payExecution}
+            else:
+                pay["settlementGate"] = {"status": "proofReady", "reason": "browserPurchaseConfirmed", "proofRequired": True}
+        else:
+            pay["settlementGate"] = {"status": "locked", "reason": str(checkout.get("reason", "purchaseFailed") or "purchaseFailed"), "proofRequired": True}
+            if checkoutNeedsInput:
+                needs = checkout.get("needsInput", []) if isinstance(checkout.get("needsInput"), list) else []
+                requested = [str(item.get("key", "") or "") for item in needs if isinstance(item, dict) and str(item.get("key", "") or "")]
+                purchaseIntent = {**purchaseIntent, "status": "needsInput", "requestedKeys": requested, "needsInput": needs}
+                bridge = {**bridge, "status": "NEEDS_INPUT", "needsInput": needs, "requestedKeys": requested}
+                pay = {**pay, "status": "AWAITING_CHECKOUT_INPUT", "requestedKeys": requested, "settlementGate": {"status": "locked", "reason": str(checkout.get("reason", "checkoutInputRequired") or "checkoutInputRequired"), "proofRequired": True}}
+        results["bridge"] = bridge
+        results["pay"] = pay
+        results["browserCheckout"] = checkout
+        results["purchaseIntent"] = purchaseIntent
+        results["hunt"] = {**(results.get("hunt", {}) if isinstance(results.get("hunt"), dict) else {}), "purchaseOutcome": purchaseOutcome}
+        results["resume"] = resume
+        event("pay", "prepare.response", "prepared", "PAY prepared a mandate and proof-gated escrow for the purchase intent.", {"mandateId": mandate.get("mandateId", ""), "escrowId": escrow.get("escrow", {}).get("escrowId", "")})
+        event("tools", "browserCheckout", str(checkout.get("status", "blocked")), "Browser tool attempted source-bound purchase execution and returned a concrete outcome.", {"ok": checkout.get("ok"), "reason": checkout.get("reason", ""), "candidateId": candidateRef["candidateId"]})
+        event("hunt", "purchase.outcome", "purchased" if purchaseOk else "blocked", "HUNT received the purchase outcome from the browser checkout attempt.", purchaseOutcome)
+        agentConversation.append("[Bridge] Making your purchase...")
+        stream("conversation", {"line": agentConversation[-1]})
+        if purchaseOk and pay.get("status") == "settled":
+            agentConversation.append("[Pay] Payment settled against the verified checkout proof.")
+        elif purchaseOk and payExecution:
+            agentConversation.append(f"[Pay] Payment is still locked: {payExecution.get('reason', 'settlementNotReleased')}.")
+        elif checkoutNeedsInput:
+            agentConversation.append("[Pay] Payment remains locked while checkout waits for the required input.")
+        else:
+            agentConversation.append("[Pay] Mandate and escrow are prepared; settlement remains proof-gated.")
+        stream("conversation", {"line": agentConversation[-1]})
+        agentConversation.append("[Hunt] Item successfully purchased." if purchaseOk else purchaseOutcome["message"])
+        stream("conversation", {"line": agentConversation[-1]})
+        return self._finalizeResume(
+            task=task,
+            priorOut=priorOut,
+            request=request,
+            conversationId=conversationId,
+            route=bridgeRoute,
+            status=purchaseStatus,
+            ok=True,
+            results=results,
+            trace=trace,
+            agentConversation=agentConversation,
+            event=event,
+            stream=stream,
+            taskStatus=ProtocolTaskStatus.PROCESSING.value,
+            evidenceStatus="verified" if purchaseOk else "sourceBound",
+            confidence=0.82 if purchaseOk else 0.58,
+            openQuestions=[] if purchaseOk else ([str(item.get("key", "") or "") for item in checkout.get("needsInput", []) if isinstance(item, dict) and str(item.get("key", "") or "")] or [str(checkout.get("reason", "purchaseFailed") or "purchaseFailed")]),
+            escalation={"recommended": not purchaseOk, "routeDomain": "bridge" if checkoutNeedsInput else ("hunt" if not purchaseOk else ""), "reason": "purchaseCompleted" if purchaseOk else str(checkout.get("reason", "purchaseFailed") or "purchaseFailed")},
+        )
+
+    def _runLocalServiceResume(
+        self,
+        *,
+        payload: dict[str, Any],
+        task: dict[str, Any],
+        priorOut: dict[str, Any],
+        hunt: dict[str, Any],
+        candidateRef: dict[str, Any],
+        request: str,
+        conversationId: str,
+        taskId: str,
+        clientId: str,
+        channel: str,
+        toolResults: dict[str, Any],
+        trace: list[dict[str, Any]],
+        agentConversation: list[str],
+        event: Any,
+        stream: Any,
+    ) -> dict[str, Any]:
+        host = self.host
+        originalRequest = self._originalTaskRequest(task) or request
+        inputs = self._localServiceInputs(payload, candidateRef, defaultBrief=originalRequest)
+        missingKeys = self._missingLocalServiceKeys(inputs, candidateRef)
+        route = ["hunt", "bridge", "proxy"]
+        proxyIntent = self._proxyContactIntent(conversationId, taskId, candidateRef, inputs, missingKeys)
+        resumeStatus = "NEEDS_INPUT" if missingKeys else "awaitingProxy"
+        resume = {
+            "action": "contact",
+            "status": resumeStatus,
+            "conversationId": conversationId,
+            "selectedCandidate": candidateRef,
+            "proxyIntent": proxyIntent,
+            "requestedKeys": missingKeys,
+            "resumeToken": self._stableId("resume", {"conversationId": conversationId, "candidateId": candidateRef["candidateId"], "action": "contact"}),
+        }
+        installed = host._ensureReadyConnectors()
+        bridgeConnectors = host.connectorBook.matchConnectors({"domain": "bridge", "caps": ["messages.send", "identity.verify", "consent.capture", "voice.call"]})
+        connectorRecords = bridgeConnectors.get("connectors", []) if isinstance(bridgeConnectors.get("connectors"), list) else []
+        connector = next((item for item in connectorRecords if isinstance(item, dict) and item.get("connectorId") == "whatsapp"), connectorRecords[0] if connectorRecords and isinstance(connectorRecords[0], dict) else {})
+        connectorId = str(connector.get("connectorId", "") or "")
+        event(
+            "bridge",
+            "connectorMatch.response",
+            "matched" if connectorId else "missingConnector",
+            "BRIDGE matched a human-contact connector for Proxy handoff." if connectorId else "BRIDGE could not match a human-contact connector for Proxy handoff.",
+            {"connectorId": connectorId, "connectorCount": bridgeConnectors.get("count", 0), "caps": ["messages.send", "identity.verify", "consent.capture", "voice.call"]},
+        )
+        results: dict[str, Any] = {
+            "tools": toolResults,
+            "hunt": {**hunt, "resume": {"action": "contact", "status": "candidateValidated", "selectedCandidate": candidateRef}},
+            "proxyIntent": proxyIntent,
+            "resume": resume,
+        }
+        if missingKeys:
+            bridge = {
+                "ok": False,
+                "status": "NEEDS_INPUT",
+                "mode": "proxyContact",
+                "requestedKeys": missingKeys,
+                "readyConnectors": installed,
+                "connectors": bridgeConnectors,
+                "contact": {
+                    "action": "requestProxyContactInput",
+                    "connectorId": connectorId,
+                    "candidateId": candidateRef.get("candidateId", ""),
+                    "businessPhone": candidateRef.get("phone", ""),
+                    "preferredChannel": inputs.get("preferredChannel", "whatsapp"),
+                },
+            }
+            proxy = {
+                "ok": False,
+                "status": "NEEDS_INPUT",
+                "requestedKeys": missingKeys,
+                "reason": "identityVerificationAndConsentRequiresInput",
+                "proxyIntent": proxyIntent,
+            }
+            results["bridge"] = bridge
+            results["proxy"] = proxy
+            event("bridge", "proxy.prepare", "NEEDS_INPUT", "BRIDGE paused Proxy handoff until required consent and contact inputs are supplied.", {"requestedKeys": missingKeys, "candidate": candidateRef})
+            event("proxy", "mission.awaitingInput", "NEEDS_INPUT", "PROXY is waiting for human-contact details before making a call or WhatsApp handoff.", {"requestedKeys": missingKeys})
+            agentConversation.append(f"[Bridge] I need {', '.join(missingKeys)} before Proxy can contact the selected service.")
+            stream("conversation", {"line": agentConversation[-1]})
+            agentConversation.append("[Proxy] Waiting for consent and contact details before calling the selected human or business.")
+            stream("conversation", {"line": agentConversation[-1]})
+            return self._finalizeResume(
+                task=task,
+                priorOut=priorOut,
+                request=request,
+                conversationId=conversationId,
+                route=route,
+                status="NEEDS_INPUT",
+                ok=True,
+                results=results,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+                taskStatus=ProtocolTaskStatus.PROCESSING.value,
+                evidenceStatus="sourceBound",
+                confidence=0.66,
+                openQuestions=missingKeys,
+                escalation={"recommended": True, "routeDomain": "proxy", "reason": "missingProxyContactInput"},
+            )
+
+        businessPhone = str(inputs.get("businessPhone", candidateRef.get("phone", "")) or "")
+        channelMsg = {
+            "channel": str(inputs.get("preferredChannel", "whatsapp") or "whatsapp"),
+            "to": businessPhone,
+            "text": f"Picux request: verify identity and consent for {candidateRef.get('title', 'selected service')}. User need: {inputs.get('issueBrief', originalRequest)}",
+            "connectorId": connectorId,
+        }
+        voiceCall = {
+            "phone": businessPhone,
+            "status": "readyToCall",
+            "prompt": f"Verify identity, availability, and consent for a Picux user request. Service: {candidateRef.get('title', '')}. Brief: {inputs.get('issueBrief', originalRequest)}",
+            "connectorId": connectorId,
+        }
+        bridge = {
+            "ok": True,
+            "status": "proxyHandoffReady",
+            "mode": "proxyContact",
+            "readyConnectors": installed,
+            "connectors": bridgeConnectors,
+            "handoffs": [{"from": "bridge", "to": "proxy", "connectorId": connectorId, "action": "identityVerificationAndConsent", "status": "sent" if connectorId else "adapterNeutral"}],
+            "contact": {"connectorId": connectorId, "channelMsg": channelMsg, "voiceCall": voiceCall, "candidate": candidateRef},
+        }
+        event("bridge", "handoff.proxy", "sent", "BRIDGE handed selected service contact to PROXY for identity verification and consent.", {"connectorId": connectorId, "candidateId": candidateRef["candidateId"], "businessPhone": businessPhone})
+        event("proxy", "mission.request", "sent", "PROXY received the selected service as a callable human/business node.", {"endpoint": "/v1/proxy/missions", "candidateId": candidateRef["candidateId"]})
+        proxyStatus, proxy = host.createProxyMission(
+            {
+                "taskId": taskId,
+                "userId": clientId,
+                "kind": "call",
+                "reason": "identityVerificationAndConsent",
+                "task": f"Contact {candidateRef.get('title') or candidateRef.get('candidateId')} for identity verification and consent.",
+                "context": {
+                    "missionState": {"route": route, "request": originalRequest, "clientId": clientId, "conversationId": conversationId},
+                    "decisionFork": {"options": ["verifyIdentityAndAvailability", "requestAnotherProvider", "stop"]},
+                    "logisticsBrief": {
+                        "why": "The user selected a local service candidate; a human/business must confirm identity, availability, and consent before the workflow can proceed.",
+                        "selectedService": candidateRef,
+                        "userPhone": inputs.get("userPhone", ""),
+                        "issueBrief": inputs.get("issueBrief", originalRequest),
+                    },
+                    "reason": "identityVerificationAndConsent",
+                    "channelMsg": channelMsg,
+                    "voiceCall": voiceCall,
+                    "connectorId": connectorId,
+                },
+                "channelMsg": channelMsg,
+                "voiceCall": voiceCall,
+                "executeProxy": True,
+                "proofReq": ["callTranscript", "consentRecord", "identityConfirmation"],
+                "resume": {"conversationId": conversationId, "candidateId": candidateRef["candidateId"], "action": "proxyOutcome"},
+            }
+        )
+        proxyCreated = proxyStatus < 400 and bool(proxy.get("ok"))
+        results["bridge"] = bridge
+        results["proxy"] = proxy
+        event("proxy", "mission.response", "awaitingProxy" if proxyCreated else "blocked", "PROXY suspended the run until the selected human/business responds." if proxyCreated else "PROXY mission could not be created.", {"proxyId": proxy.get("proxyId", ""), "status": proxyStatus})
+        agentConversation.append("[Bridge] Routing the selected service through WhatsApp or voice contact.")
+        stream("conversation", {"line": agentConversation[-1]})
+        agentConversation.append("[Proxy] Calling the selected human or business for identity verification and consent.")
+        stream("conversation", {"line": agentConversation[-1]})
+        return self._finalizeResume(
+            task=task,
+            priorOut=priorOut,
+            request=request,
+            conversationId=conversationId,
+            route=route,
+            status="awaitingProxy" if proxyCreated else "proxyBlocked",
+            ok=proxyCreated,
+            results=results,
+            trace=trace,
+            agentConversation=agentConversation,
+            event=event,
+            stream=stream,
+            taskStatus=ProtocolTaskStatus.AWAITING_PROXY.value if proxyCreated else ProtocolTaskStatus.PROCESSING.value,
+            evidenceStatus="sourceBound",
+            confidence=0.74 if proxyCreated else 0.5,
+            openQuestions=["awaitingProxyOutcome"] if proxyCreated else ["proxyMissionRequired"],
+            escalation={"recommended": True, "routeDomain": "proxy", "reason": "awaitingProxy" if proxyCreated else "proxyBlocked"},
+        )
+
+    def _runCandidateContactResume(
+        self,
+        *,
+        payload: dict[str, Any],
+        task: dict[str, Any],
+        priorOut: dict[str, Any],
+        hunt: dict[str, Any],
+        candidateRef: dict[str, Any],
+        request: str,
+        conversationId: str,
+        taskId: str,
+        clientId: str,
+        toolResults: dict[str, Any],
+        trace: list[dict[str, Any]],
+        agentConversation: list[str],
+        event: Any,
+        stream: Any,
+    ) -> dict[str, Any]:
+        host = self.host
+        contact = str(payload.get("sellerContact", payload.get("contact", payload.get("to", ""))) or "")
+        message = str(payload.get("message", payload.get("text", request)) or request)
+        missing = []
+        if not contact:
+            missing.append("sellerContact")
+        if not message.strip():
+            missing.append("message")
+        route = ["hunt", "bridge", "proxy"]
+        resume = {
+            "action": "contact",
+            "status": "NEEDS_INPUT" if missing else "awaitingProxy",
+            "conversationId": conversationId,
+            "selectedCandidate": candidateRef,
+            "requestedKeys": missing,
+        }
+        results: dict[str, Any] = {"tools": toolResults, "hunt": {**hunt, "resume": resume}, "resume": resume}
+        if missing:
+            results["bridge"] = {"ok": False, "status": "NEEDS_INPUT", "requestedKeys": missing, "candidate": candidateRef}
+            results["proxy"] = {"ok": False, "status": "NEEDS_INPUT", "requestedKeys": missing, "reason": "sellerContactRequired"}
+            event("bridge", "sellerContact.awaitingInput", "NEEDS_INPUT", "BRIDGE needs a seller contact or channel reference before Proxy can contact this source.", {"candidate": candidateRef, "requestedKeys": missing})
+            agentConversation.append("[Bridge] I need the seller contact or channel reference before Proxy can contact this option.")
+            stream("conversation", {"line": agentConversation[-1]})
+            return self._finalizeResume(
+                task=task,
+                priorOut=priorOut,
+                request=request,
+                conversationId=conversationId,
+                route=route,
+                status="NEEDS_INPUT",
+                ok=True,
+                results=results,
+                trace=trace,
+                agentConversation=agentConversation,
+                event=event,
+                stream=stream,
+                taskStatus=ProtocolTaskStatus.PROCESSING.value,
+                evidenceStatus="sourceBound",
+                confidence=0.6,
+                openQuestions=missing,
+                escalation={"recommended": True, "routeDomain": "bridge", "reason": "sellerContactRequired"},
+            )
+        installed = host._ensureReadyConnectors()
+        isPhone = bool(re.search(r"\+?\d[\d\s().-]{6,}", contact))
+        bridgeConnectors = host.connectorBook.matchConnectors({"domain": "bridge", "caps": ["voice.call" if isPhone else "messages.send"]})
+        connectorRecords = bridgeConnectors.get("connectors", []) if isinstance(bridgeConnectors.get("connectors"), list) else []
+        preferred = "twilioVoice" if isPhone else "whatsapp"
+        connector = next((item for item in connectorRecords if isinstance(item, dict) and item.get("connectorId") == preferred), connectorRecords[0] if connectorRecords and isinstance(connectorRecords[0], dict) else {})
+        connectorId = str(connector.get("connectorId", "") or "")
+        voiceCall = {"phone": contact, "status": "readyToCall", "prompt": message, "connectorId": connectorId} if isPhone else {}
+        channelMsg = {"channel": "message", "to": contact, "text": message, "connectorId": connectorId} if not isPhone else {}
+        proxyStatus, proxy = host.createProxyMission(
+            {
+                "taskId": taskId,
+                "userId": clientId,
+                "kind": "call" if isPhone else "message",
+                "reason": "sellerContact",
+                "task": f"Contact the selected source-bound option: {candidateRef.get('title') or candidateRef.get('candidateId')}.",
+                "context": {
+                    "missionState": {"route": route, "request": request, "clientId": clientId, "conversationId": conversationId},
+                    "selectedCandidate": candidateRef,
+                    "sellerContact": contact,
+                    "reason": "sellerContact",
+                    "connectorId": connectorId,
+                },
+                "voiceCall": voiceCall,
+                "channelMsg": channelMsg,
+                "executeProxy": True,
+                "proofReq": ["messageTranscript", "availabilityConfirmation", "consentRecord"],
+                "resume": {"conversationId": conversationId, "candidateId": candidateRef["candidateId"], "action": "proxyOutcome"},
+            }
+        )
+        proxyCreated = proxyStatus < 400 and bool(proxy.get("ok"))
+        results["bridge"] = {"ok": bool(connectorId), "status": "proxyHandoffReady" if connectorId else "missingConnector", "readyConnectors": installed, "connectors": bridgeConnectors}
+        results["proxy"] = proxy
+        event("proxy", "mission.response", "awaitingProxy" if proxyCreated else "blocked", "PROXY started seller contact for the selected source-bound option." if proxyCreated else "PROXY could not start seller contact.", {"proxyId": proxy.get("proxyId", ""), "connectorId": connectorId})
+        agentConversation.append("[Proxy] Contacting the selected source and waiting for confirmation proof.")
+        stream("conversation", {"line": agentConversation[-1]})
+        return self._finalizeResume(
+            task=task,
+            priorOut=priorOut,
+            request=request,
+            conversationId=conversationId,
+            route=route,
+            status="awaitingProxy" if proxyCreated else "proxyBlocked",
+            ok=proxyCreated,
+            results=results,
+            trace=trace,
+            agentConversation=agentConversation,
+            event=event,
+            stream=stream,
+            taskStatus=ProtocolTaskStatus.AWAITING_PROXY.value if proxyCreated else ProtocolTaskStatus.PROCESSING.value,
+            evidenceStatus="sourceBound",
+            confidence=0.7 if proxyCreated else 0.48,
+            openQuestions=["awaitingProxyOutcome"] if proxyCreated else ["proxyMissionRequired"],
+            escalation={"recommended": True, "routeDomain": "proxy", "reason": "awaitingProxy" if proxyCreated else "proxyBlocked"},
+        )
+
+    def _finalizeResume(
+        self,
+        *,
+        task: dict[str, Any],
+        priorOut: dict[str, Any],
+        request: str,
+        conversationId: str,
+        route: list[str],
+        status: str,
+        ok: bool,
+        results: dict[str, Any],
+        trace: list[dict[str, Any]],
+        agentConversation: list[str],
+        event: Any,
+        stream: Any,
+        taskStatus: str,
+        evidenceStatus: str,
+        confidence: float,
+        openQuestions: list[str],
+        escalation: dict[str, Any],
+    ) -> dict[str, Any]:
+        host = self.host
+        taskId = str(task.get("taskId", "") or conversationId or self._stableId("task", {"request": request, "status": status}))
+        priorResults = priorOut.get("results", {}) if isinstance(priorOut.get("results"), dict) else {}
+        mergedResults = {**priorResults, **results}
+        decisionTree = self._decisionTree(mergedResults.get("hunt", {}))
+        event("orchestrator", "proofPack", "created", "Picux updated the portable proof card for the resumed conversation.", {"status": status, "conversationId": conversationId})
+        proof = host._proofPackForRun(
+            taskId=taskId,
+            domain="orchestrator",
+            title="Picux resumed conversation",
+            summary=f"Picux resumed {conversationId or taskId} through {', '.join(route).upper()} with status {status}.",
+            payload={"request": request, "conversationId": conversationId, "route": route, "results": mergedResults},
+            decisions=[{"label": item["name"], "reason": item["status"]} for item in trace if item["phase"] != "orchestrator"],
+            evidenceStatus=evidenceStatus,
+            confidence=confidence,
+            openQuestions=openQuestions,
+            escalation=escalation,
+        )
+        agentConversation.append("[Picux] I updated the conversation state, next action, evidence status, open questions, and proof card.")
+        stream("conversation", {"line": agentConversation[-1]})
+        resumeState = results.get("resume", {}) if isinstance(results.get("resume"), dict) else {}
+        nextOut = {
+            **priorOut,
+            "conversationId": conversationId,
+            "route": route,
+            "status": status,
+            "results": mergedResults,
+            "resume": resumeState,
+            "decisionTree": decisionTree,
+            "proofPack": proof.get("proofPack", {}),
+        }
+        nextMeta = {**(task.get("meta", {}) if isinstance(task.get("meta"), dict) else {}), "conversationId": conversationId}
+        updated = host.taskBook.updateTask(taskId, {"status": taskStatus, "outData": nextOut, "meta": nextMeta})
+        if updated.get("ok"):
+            task = updated["task"]
+        pay = mergedResults.get("pay", {}) if isinstance(mergedResults.get("pay"), dict) else {}
+        mandateResult = pay.get("mandate", {}) if isinstance(pay.get("mandate"), dict) else {}
+        return {
+            "ok": ok,
+            "scenario": "picuxOrchestrator",
+            "status": status,
+            "conversationId": conversationId,
+            "request": request,
+            "route": route,
+            "task": task,
+            "trace": trace,
+            "agentConversation": agentConversation,
+            "results": mergedResults,
+            "decisionTree": decisionTree,
+            "mandate": mandateResult.get("mandate", mandateResult) if isinstance(mandateResult, dict) else {},
+            "receipt": None,
+            "freezeReceipt": None,
+            "proofPack": proof.get("proofPack", {}),
+            "proofCard": proof.get("proofPack", {}).get("proofCard", {}),
+        }
+
+    def _resumeFailure(
+        self,
+        *,
+        request: str,
+        route: list[str],
+        status: str,
+        error: str,
+        conversationId: str,
+        clientId: str,
+        channel: str,
+        trace: list[dict[str, Any]],
+        agentConversation: list[str],
+        results: dict[str, Any],
+        event: Any,
+        stream: Any,
+    ) -> dict[str, Any]:
+        taskId = self._stableId("resume", {"request": request, "conversationId": conversationId, "error": error})
+        event("orchestrator", "proofPack", "created", "Picux created a proof card for the failed resume attempt.", {"status": status, "error": error})
+        proof = self.host._proofPackForRun(
+            taskId=taskId,
+            domain="orchestrator",
+            title="Picux resume failed",
+            summary=f"Picux could not resume the conversation: {error}.",
+            payload={"request": request, "conversationId": conversationId, "client": {"clientId": clientId, "channel": channel}, "results": results},
+            decisions=[{"label": item["name"], "reason": item["status"]} for item in trace if item["phase"] != "orchestrator"],
+            evidenceStatus="needsEvidence",
+            confidence=0.2,
+            openQuestions=["validConversationIdRequired"],
+            escalation={"recommended": True, "routeDomain": "orchestrator", "reason": error},
+        )
+        agentConversation.append("[Picux] I could not resume that conversation. Send a valid conversationId from the previous result.")
+        stream("conversation", {"line": agentConversation[-1]})
+        return {
+            "ok": False,
+            "scenario": "picuxOrchestrator",
+            "status": status,
+            "conversationId": conversationId,
+            "request": request,
+            "route": route,
+            "task": {},
+            "trace": trace,
+            "agentConversation": agentConversation,
+            "results": {**results, "resume": {"ok": False, "error": error, "conversationId": conversationId}},
+            "decisionTree": {"root": "userRequest", "selected": "", "paths": []},
+            "mandate": {},
+            "receipt": None,
+            "freezeReceipt": None,
+            "proofPack": proof.get("proofPack", {}),
+            "proofCard": proof.get("proofPack", {}).get("proofCard", {}),
+        }
+
+    def _route(self, request: str, payload: dict[str, Any]) -> list[str]:
+        rawRoute = payload.get("domainRoute", payload.get("route", []))
+        route = [str(item).strip().lower() for item in rawRoute if isinstance(item, str)] if isinstance(rawRoute, list) else []
+        route = [item for item in route if item in self.domains]
+        resolveCase = self._isResolveCase(request)
+        if not route:
+            seed = self.host.router.classify(request).domain.value
+            explicitResolve = resolveCase
+            explicitPay = any(token in request.lower() 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 self._shouldCreateProxy(request, payload):
+                seed = "resolve" if explicitResolve else "hunt"
+            if explicitResolve and seed in {"hunt", "bridge"}:
+                seed = "resolve"
+            route = [seed]
+
+        lowered = request.lower()
+        if not resolveCase and self._isLocalServiceRequest(request, payload, {"entities": {}}) and "hunt" not in route:
+            route.insert(0, "hunt")
+        if not resolveCase and any(token in lowered for token in ("find", "near", "within", "km", "buy", "shop", "shopping", "best", "option", "lead", "opportunity", "source", "market", "mechanic", "plumber", "electrician", "repair")) and "hunt" not in route:
+            route.insert(0, "hunt")
+        if resolveCase and "resolve" not in route:
+            route.append("resolve")
+        if any(token in lowered for token in ("email", "merchant", "bank", "service", "support", "api", "webhook", "connector", "whatsapp", "chat", "representative", "followup", "follow up")) and "bridge" not in route:
+            insertAt = route.index("resolve") + 1 if "resolve" in route else len(route)
+            route.insert(insertAt, "bridge")
+        if self._shouldCreateProxy(request, payload) and "proxy" not in route:
+            route.append("proxy")
+        if any(token in lowered for token in ("pay", "payment", "settle", "settlement", "escrow")) 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")
+        route = list(dict.fromkeys(route or ["hunt"]))
+        if resolveCase and "hunt" not in route:
+            order = ["resolve", "bridge", "proxy", "pay"]
+            return [domain for domain in order if domain in route]
+        return route
+
+    @staticmethod
+    def _ensureRouteAfter(route: list[str], *, after: str, domains: list[str]) -> None:
+        insertAt = route.index(after) + 1 if after in route else len(route)
+        for domain in domains:
+            if domain in route:
+                continue
+            route.insert(insertAt, domain)
+            insertAt += 1
+
+    def _verifiedLocalServiceMapResult(self, host: Any, request: str, payload: dict[str, Any], nlp: dict[str, Any]) -> dict[str, Any]:
+        if not hasattr(host, "localProviderBook"):
+            return {}
+        entities = nlp.get("entities", {}) if isinstance(nlp.get("entities"), dict) else {}
+        entity = str(payload.get("entity", payload.get("service", entities.get("service", entities.get("entity", "")))) or "")
+        location = str(payload.get("location", payload.get("near", entities.get("location", ""))) or "")
+        radiusKm = self._float(payload.get("radiusKm", payload.get("distanceKm", entities.get("radiusKm", 10.0))))
+        places = host.localProviderBook.toPlaces(service=entity, location=location, limit=10)
+        if not places:
+            return {}
+        return {
+            "ok": True,
+            "tool": "mapTool",
+            "provider": "verifiedProviders",
+            "status": "found",
+            "query": {
+                "text": request,
+                "entity": entity or self._itemId(request),
+                "location": location,
+                "radiusKm": radiusKm or 10.0,
+                "radiusMeters": int(max(1.0, radiusKm or 10.0) * 1000),
+            },
+            "places": places,
+            "errors": [],
+            "networkAttempted": False,
+        }
+
+    @classmethod
+    def _publicMapResult(cls, mapResult: dict[str, Any]) -> dict[str, Any]:
+        public = json.loads(json.dumps(mapResult, ensure_ascii=True, default=str))
+        places = public.get("places", []) if isinstance(public.get("places"), list) else []
+        public["places"] = [cls._publicPlace(place) for place in places if isinstance(place, dict)]
+        return public
+
+    @staticmethod
+    def _publicPlace(place: dict[str, Any]) -> dict[str, Any]:
+        clean = dict(place)
+        for key in ("phone", "phoneNumber", "international_phone_number", "formatted_phone_number"):
+            clean.pop(key, None)
+        return clean
+
+    @classmethod
+    def _localServiceContactRefs(cls, mapResult: dict[str, Any], offers: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+        places = mapResult.get("places", []) if isinstance(mapResult.get("places"), list) else []
+        query = mapResult.get("query", {}) if isinstance(mapResult.get("query"), dict) else {}
+        offersByPlaceId = {}
+        offersByIndex = {}
+        for offer in offers:
+            meta = offer.get("meta", {}) if isinstance(offer.get("meta"), dict) else {}
+            placeId = str(meta.get("placeId", "") or "")
+            if placeId:
+                offersByPlaceId[placeId] = offer
+            offersByIndex[int(meta.get("placeIndex", 0) or 0)] = offer
+        contacts: dict[str, dict[str, Any]] = {}
+        for index, place in enumerate(places[:10], start=1):
+            if not isinstance(place, dict):
+                continue
+            placeId = str(place.get("placeId", "") or "")
+            offer = offersByPlaceId.get(placeId) or offersByIndex.get(index) or {}
+            meta = offer.get("meta", {}) if isinstance(offer.get("meta"), dict) else {}
+            candidateId = str(offer.get("candidateId", offer.get("sourceId", meta.get("candidateId", ""))) or "")
+            contactRef = str(meta.get("contactRef", place.get("contactRef", "")) or cls._contactRefForPlace(place, candidateId))
+            contact = {
+                "providerId": contactRef,
+                "contactRef": contactRef,
+                "candidateId": candidateId or contactRef,
+                "service": str(query.get("entity", place.get("entity", "")) or ""),
+                "entity": str(query.get("entity", place.get("entity", "")) or ""),
+                "location": str(query.get("location", "") or ""),
+                "name": str(place.get("name", "") or ""),
+                "category": str(place.get("category", "") or ""),
+                "address": str(place.get("address", "") or ""),
+                "phone": str(place.get("phone", "") or ""),
+                "website": str(place.get("website", "") or ""),
+                "rating": place.get("rating", 0),
+                "lat": place.get("lat", 0),
+                "lng": place.get("lng", 0),
+                "distanceKm": place.get("distanceKm", 0),
+                "source": str(place.get("source", mapResult.get("provider", "")) or ""),
+                "sourceUrl": str(place.get("sourceUrl", "") or ""),
+                "meta": {"placeId": placeId, "provider": mapResult.get("provider", ""), "sourceBound": bool(place.get("sourceBound"))},
+            }
+            contacts[contact["candidateId"]] = contact
+            contacts[contactRef] = contact
+            if placeId:
+                contacts[placeId] = contact
+        return contacts
+
+    @staticmethod
+    def _cacheLocalServiceLeads(host: Any, contacts: dict[str, dict[str, Any]]) -> None:
+        if not hasattr(host, "localProviderBook"):
+            return
+        seen: set[str] = set()
+        for contact in contacts.values():
+            contactRef = str(contact.get("contactRef", "") or "")
+            if not contactRef or contactRef in seen:
+                continue
+            seen.add(contactRef)
+            try:
+                host.localProviderBook.saveLead(contact)
+            except Exception:
+                continue
+
+    @classmethod
+    def _selectedLocalServiceContact(cls, hunt: dict[str, Any], contacts: dict[str, dict[str, Any]]) -> dict[str, Any]:
+        if not isinstance(hunt, dict):
+            return {}
+        selected = hunt.get("selected", {}) if isinstance(hunt.get("selected"), dict) else {}
+        meta = selected.get("meta", {}) if isinstance(selected.get("meta"), dict) else {}
+        keys = [
+            str(selected.get("candidateId", "") or ""),
+            str(selected.get("sourceId", "") or ""),
+            str(meta.get("contactRef", "") or ""),
+            str(meta.get("placeId", "") or ""),
+        ]
+        for key in keys:
+            if key and key in contacts:
+                return contacts[key]
+        if selected and cls._isLocalServiceCandidate(cls._candidateRef(selected)):
+            ref = cls._candidateRef(selected)
+            contactRef = str(meta.get("contactRef", ref.get("candidateId", "")) or "")
+            return {
+                "providerId": contactRef or ref.get("candidateId", ""),
+                "contactRef": contactRef or ref.get("candidateId", ""),
+                "candidateId": ref.get("candidateId", ""),
+                "service": str(meta.get("entity", selected.get("itemId", "")) or ""),
+                "entity": str(meta.get("entity", selected.get("itemId", "")) or ""),
+                "location": "",
+                "name": ref.get("title", ""),
+                "category": "",
+                "address": ref.get("address", ""),
+                "website": ref.get("website", ""),
+                "rating": ref.get("rating", 0),
+                "source": ref.get("source", ""),
+                "sourceUrl": ref.get("url", ""),
+                "meta": {"sourceBound": True},
+            }
+        return {}
+
+    @staticmethod
+    def _publicLocalServiceContact(contact: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "providerId": str(contact.get("providerId", contact.get("contactRef", "")) or ""),
+            "contactRef": str(contact.get("contactRef", contact.get("providerId", "")) or ""),
+            "candidateId": str(contact.get("candidateId", "") or ""),
+            "service": str(contact.get("service", contact.get("entity", "")) or ""),
+            "location": str(contact.get("location", "") or ""),
+            "name": str(contact.get("name", "") or ""),
+            "category": str(contact.get("category", "") or ""),
+            "address": str(contact.get("address", "") or ""),
+            "website": str(contact.get("website", "") or ""),
+            "rating": contact.get("rating", 0),
+            "distanceKm": contact.get("distanceKm", 0),
+            "source": str(contact.get("source", "") or ""),
+            "sourceUrl": str(contact.get("sourceUrl", "") or ""),
+            "status": str(contact.get("status", "lead") or "lead"),
+        }
+
+    @staticmethod
+    def _selectBridgeConnector(match: dict[str, Any], *, preferred: tuple[str, ...]) -> dict[str, Any]:
+        records = [item for item in match.get("connectors", []) if isinstance(item, dict)] if isinstance(match, dict) else []
+        if not records:
+            return {}
+        preferredIndex = {connectorId: index for index, connectorId in enumerate(preferred)}
+
+        def score(item: dict[str, Any]) -> tuple[int, int, int]:
+            meta = item.get("meta", {}) if isinstance(item.get("meta"), dict) else {}
+            connectorId = str(item.get("connectorId", "") or "")
+            return (
+                1 if not meta.get("readyMade") else 0,
+                len(preferred) - preferredIndex.get(connectorId, len(preferred)),
+                int(item.get("createdAt", 0) or 0),
+            )
+
+        records.sort(key=score, reverse=True)
+        return records[0]
+
+    @staticmethod
+    def _connectorPreflight(host: Any, connectorId: str, *, action: str, resource: str) -> dict[str, Any]:
+        if not connectorId or not hasattr(host, "preflightConnector"):
+            return {"ok": False, "status": "blocked", "connectorId": connectorId, "errors": ["missingConnector"]}
+        try:
+            return host.preflightConnector(connectorId, {"action": action, "resource": resource})
+        except Exception as exc:
+            return {"ok": False, "status": "blocked", "connectorId": connectorId, "errors": [type(exc).__name__]}
+
+    @staticmethod
+    def _followUpAction(payload: dict[str, Any]) -> str:
+        raw = payload.get("action", payload.get("intent", payload.get("key", "")))
+        if isinstance(raw, bool):
+            raw = "buy" if raw else ""
+        action = str(raw or "").strip().lower()
+        if not action and payload.get("buy") is not None:
+            action = "buy" if bool(payload.get("buy")) else ""
+        if not action and payload.get("pass") is not None:
+            action = "pass" if bool(payload.get("pass")) else ""
+        aliases = {
+            "purchase": "buy",
+            "checkout": "buy",
+            "select": "buy",
+            "selected": "buy",
+            "accept": "buy",
+            "ask": "contact",
+            "message": "contact",
+            "call": "contact",
+            "contact": "contact",
+            "availability": "contact",
+            "pay": "paymentInfo",
+            "payment": "paymentInfo",
+            "refine": "refine",
+            "change": "refine",
+            "skip": "pass",
+            "reject": "pass",
+            "decline": "pass",
+        }
+        action = aliases.get(action, action)
+        return action if action in {"buy", "pass", "contact", "paymentInfo", "refine"} else ""
+
+    @staticmethod
+    def _followUpTextAction(request: str) -> str:
+        text = f" {str(request or '').strip().lower()} "
+        if not text.strip():
+            return ""
+        if re.search(r"\b(buy|purchase|checkout|order|get it|take it|select|choose|pick)\b", text):
+            return "buy"
+        if re.search(r"\b(ask|message|contact|call|availability|available|deliver|delivery|negotiate)\b", text):
+            return "contact"
+        if re.search(r"\b(pay|payment|swish|stripe|paypal|card|bank|bitcoin|wallet)\b", text):
+            return "paymentInfo"
+        if re.search(r"\b(change|increase|decrease|budget|cheaper|closer|different|refine|filter)\b", text):
+            return "refine"
+        if re.search(r"\b(pass|skip|decline|reject|next option|not this|no thanks)\b", text):
+            return "pass"
+        return ""
+
+    @staticmethod
+    def _hasConversationState(host: Any, conversationId: str) -> bool:
+        if not conversationId or not hasattr(host, "taskBook"):
+            return False
+        try:
+            lookup = host.taskBook.getTaskByConversationId(conversationId) if hasattr(host.taskBook, "getTaskByConversationId") else host.taskBook.getTask(conversationId)
+        except Exception:
+            return False
+        return bool(lookup.get("ok"))
+
+    @staticmethod
+    def _resumeRequestLabel(action: str, payload: dict[str, Any]) -> str:
+        itemId = PicuxMultiAgentOrchestrator._selectedItemId(payload)
+        if action == "pass":
+            return f"Pass on selected item {itemId}".strip()
+        if action == "buy":
+            return f"Buy selected item {itemId}".strip()
+        return "Resume Picux conversation"
+
+    @staticmethod
+    def _conversationId(payload: dict[str, Any]) -> str:
+        raw = (
+            payload.get("conversationId")
+            or payload.get("conversationid")
+            or payload.get("conversationID")
+            or payload.get("taskId")
+            or payload.get("resumeToken")
+            or ""
+        )
+        return str(raw or "").strip()
+
+    @classmethod
+    def _selectedItemId(cls, payload: dict[str, Any], hunt: dict[str, Any] | None = None, request: str = "") -> str:
+        raw = payload.get("itemId") or payload.get("candidateId") or payload.get("sourceId") or payload.get("vendorId") or payload.get("selectedId") or ""
+        selected = payload.get("selected") if isinstance(payload.get("selected"), dict) else {}
+        if not raw and selected:
+            raw = selected.get("itemId") or selected.get("candidateId") or selected.get("sourceId") or selected.get("vendorId") or ""
+        if raw:
+            return str(raw or "").strip()
+        if hunt:
+            ordinal = cls._selectedOrdinal(payload, request=request)
+            if ordinal:
+                candidates = cls._candidateList(hunt)
+                if 0 < ordinal <= len(candidates):
+                    ref = cls._candidateRef(candidates[ordinal - 1])
+                    return str(ref.get("candidateId", ref.get("sourceId", ref.get("itemId", ""))) or "")
+        return ""
+
+    @staticmethod
+    def _selectedOrdinal(payload: dict[str, Any], request: str = "") -> int:
+        raw = payload.get("index", payload.get("itemIndex", payload.get("rank", payload.get("position", ""))))
+        if isinstance(raw, int):
+            return raw
+        text = f" {str(raw or '')} {str(request or payload.get('request', payload.get('query', payload.get('message', ''))) or '')} ".lower()
+        if not text.strip():
+            return 0
+        numeric = re.search(r"(?:#|item|option|result|candidate|the)?\s*(\d+)(?:st|nd|rd|th)?\b", text)
+        if numeric:
+            try:
+                return int(numeric.group(1))
+            except ValueError:
+                return 0
+        words = {
+            "first": 1,
+            "second": 2,
+            "third": 3,
+            "fourth": 4,
+            "fifth": 5,
+            "sixth": 6,
+            "seventh": 7,
+            "eighth": 8,
+            "ninth": 9,
+            "tenth": 10,
+            "one": 1,
+            "two": 2,
+            "three": 3,
+            "four": 4,
+            "five": 5,
+            "six": 6,
+            "seven": 7,
+            "eight": 8,
+            "nine": 9,
+            "ten": 10,
+        }
+        for word, ordinal in words.items():
+            if re.search(rf"\b{word}\b", text):
+                return ordinal
+        return 0
+
+    @staticmethod
+    def _resumeRoute(action: str) -> list[str]:
+        if action == "buy":
+            return ["hunt", "bridge", "pay"]
+        if action == "contact":
+            return ["hunt", "bridge", "proxy"]
+        if action == "paymentInfo":
+            return ["hunt", "pay"]
+        if action == "refine":
+            return ["hunt"]
+        return ["hunt"]
+
+    @classmethod
+    def _candidateById(cls, hunt: dict[str, Any], itemId: str) -> dict[str, Any] | None:
+        itemId = str(itemId or "").strip()
+        if not itemId:
+            return None
+        candidates = cls._candidateList(hunt)
+        exactKeys = ("candidateId", "sourceId", "vendorId", "id")
+        for candidate in candidates:
+            meta = candidate.get("meta", {}) if isinstance(candidate.get("meta"), dict) else {}
+            values = [str(candidate.get(key, "") or "") for key in exactKeys]
+            values.extend(str(meta.get(key, "") or "") for key in ("candidateId", "sourceId", "vendorId", "id"))
+            if itemId in values:
+                return candidate
+        semanticMatches = [candidate for candidate in candidates if str(candidate.get("itemId", "") or "") == itemId]
+        return semanticMatches[0] if len(semanticMatches) == 1 else None
+
+    @staticmethod
+    def _candidateList(hunt: dict[str, Any]) -> list[dict[str, Any]]:
+        candidates = hunt.get("candidates", []) if isinstance(hunt.get("candidates"), list) else []
+        clean = [item for item in candidates if isinstance(item, dict)]
+        if clean:
+            return clean
+        selected = hunt.get("selected", {}) if isinstance(hunt.get("selected"), dict) else {}
+        return [selected] if selected else []
+
+    @classmethod
+    def _candidateRefs(cls, hunt: dict[str, Any]) -> list[dict[str, Any]]:
+        return [cls._candidateRef(candidate) for candidate in cls._candidateList(hunt)]
+
+    @staticmethod
+    def _candidateRef(candidate: dict[str, Any]) -> dict[str, Any]:
+        meta = candidate.get("meta", {}) if isinstance(candidate.get("meta"), dict) else {}
+        price = meta.get("price", {}) if isinstance(meta.get("price"), dict) else {}
+        sourceId = str(candidate.get("sourceId", candidate.get("vendorId", "")) or "")
+        candidateId = str(candidate.get("candidateId", meta.get("candidateId", sourceId)) or sourceId)
+        return {
+            "candidateId": candidateId,
+            "sourceId": sourceId,
+            "itemId": str(candidate.get("itemId", "") or ""),
+            "title": str(candidate.get("title", meta.get("listingTitle", candidate.get("itemId", ""))) or ""),
+            "source": str(meta.get("source", "") or ""),
+            "url": str(candidate.get("url", meta.get("sourceUrl", "")) or ""),
+            "kind": str(meta.get("kind", meta.get("placeKind", "")) or ""),
+            "address": str(meta.get("address", "") or ""),
+            "website": str(meta.get("website", "") or ""),
+            "rating": meta.get("rating", 0),
+            "distanceKm": meta.get("distanceKm", 0),
+            "price": price,
+            "netUsd": float(candidate.get("netUsd", candidate.get("offerUsd", 0.0)) or 0.0),
+            "eligible": bool(candidate.get("eligible", True)),
+            "reasons": candidate.get("reasons", []) if isinstance(candidate.get("reasons"), list) else [],
+        }
+
+    @staticmethod
+    def _rejectedCandidateIds(priorOut: dict[str, Any]) -> list[str]:
+        resume = priorOut.get("resume", {}) if isinstance(priorOut.get("resume"), dict) else {}
+        rejected = resume.get("rejectedCandidateIds", []) if isinstance(resume.get("rejectedCandidateIds"), list) else []
+        return [str(item) for item in rejected if str(item)]
+
+    @classmethod
+    def _nextCandidateRef(cls, hunt: dict[str, Any], rejected: list[str]) -> dict[str, Any]:
+        rejectedSet = set(rejected)
+        for candidate in cls._candidateList(hunt):
+            ref = cls._candidateRef(candidate)
+            if ref["candidateId"] in rejectedSet:
+                continue
+            if candidate.get("eligible", True):
+                return ref
+        return {}
+
+    @staticmethod
+    def _purchaseInputs(payload: dict[str, Any]) -> dict[str, Any]:
+        rawInputs = payload.get("inputs") if isinstance(payload.get("inputs"), dict) else {}
+        values = payload.get("values") if isinstance(payload.get("values"), dict) else {}
+        contact = payload.get("contact") if isinstance(payload.get("contact"), dict) else {}
+        shipping = payload.get("shipping") if isinstance(payload.get("shipping"), dict) else {}
+        billing = payload.get("billing") if isinstance(payload.get("billing"), dict) else {}
+        payment = payload.get("payment") if isinstance(payload.get("payment"), dict) else {}
+        inputs = {**rawInputs, **values}
+        email = payload.get("email") or inputs.get("email") or contact.get("email") or ""
+        phone = payload.get("phone") or inputs.get("phone") or contact.get("phone") or ""
+        shippingAddress = payload.get("shippingAddress") or inputs.get("shippingAddress") or payload.get("address") or inputs.get("address") or shipping.get("address") or shipping.get("shippingAddress") or ""
+        billingAddress = payload.get("billingAddress") or inputs.get("billingAddress") or billing.get("address") or billing.get("billingAddress") or ""
+        if not billingAddress and bool(payload.get("billingSameAsShipping", inputs.get("billingSameAsShipping", False))):
+            billingAddress = shippingAddress
+        return {
+            "email": email,
+            "phone": phone,
+            "shippingAddress": shippingAddress,
+            "billingAddress": billingAddress,
+            "paymentMethod": payload.get("paymentMethod") or inputs.get("paymentMethod") or payment.get("method") or payment.get("paymentMethod") or "",
+            "walletAddress": payload.get("walletAddress") or inputs.get("walletAddress") or payment.get("walletAddress") or "",
+            "chainType": payload.get("chainType") or inputs.get("chainType") or payment.get("chainType") or payment.get("chain") or "",
+            "cardNumber": payload.get("cardNumber") or inputs.get("cardNumber") or payment.get("cardNumber") or "",
+            "expiry": payload.get("expiry") or inputs.get("expiry") or payment.get("expiry") or "",
+            "cvv": payload.get("cvv") or inputs.get("cvv") or payment.get("cvv") or "",
+            "account": payload.get("account") or inputs.get("account") or payment.get("account") or "",
+            "number": payload.get("number") or inputs.get("number") or payment.get("number") or "",
+            "bank": payload.get("bank") or inputs.get("bank") or payment.get("bank") or "",
+            "card": payload.get("card") or inputs.get("card") or payment.get("card") or "",
+            "paymentToken": payload.get("paymentToken") or inputs.get("paymentToken") or payment.get("token") or "",
+            "mandateId": payload.get("mandateId") or inputs.get("mandateId") or payment.get("mandateId") or "",
+        }
+
+    @staticmethod
+    def _missingContactKeys(inputs: dict[str, Any]) -> list[str]:
+        missing = []
+        if not str(inputs.get("email", "") or "").strip():
+            missing.append("email")
+        if not str(inputs.get("shippingAddress", "") or "").strip():
+            missing.append("shippingAddress")
+        if not str(inputs.get("billingAddress", "") or "").strip():
+            missing.append("billingAddress")
+        return missing
+
+    @classmethod
+    def _missingPaymentKeys(cls, inputs: dict[str, Any]) -> list[str]:
+        method = str(inputs.get("paymentMethod", "") or "").strip().lower()
+        if not method or method not in cls._supportedPaymentMethods():
+            return ["paymentMethod"]
+        required = cls._paymentFieldsFor(method)
+        return [key for key in required if not str(inputs.get(key, "") or "").strip()]
+
+    @classmethod
+    def _purchaseIntent(cls, conversationId: str, taskId: str, candidateRef: dict[str, Any], inputs: dict[str, Any], missingKeys: list[str], resumeStatus: str) -> dict[str, Any]:
+        intentId = cls._stableId("purchase", {"conversationId": conversationId, "taskId": taskId, "candidateId": candidateRef.get("candidateId", "")})
+        status = {"NEEDS_INPUT": "needsInput", "NEEDS_PAYMENT_INFO": "needsPaymentInfo"}.get(resumeStatus, "readyForCheckout")
+        return {
+            "intentId": intentId,
+            "conversationId": conversationId,
+            "taskId": taskId,
+            "status": status,
+            "candidate": candidateRef,
+            "requestedKeys": missingKeys,
+            "requiredKeys": ["email", "shippingAddress", "billingAddress"],
+            "supportedPaymentMethods": cls._supportedPaymentMethods(),
+            "paymentSchema": cls._paymentSchema(),
+            "inputs": cls._safePurchaseInputs(inputs),
+        }
+
+    @staticmethod
+    def _safePurchaseInputs(inputs: dict[str, Any]) -> dict[str, Any]:
+        safe: dict[str, Any] = {}
+        for key in ("email", "phone", "shippingAddress", "billingAddress", "paymentMethod", "walletAddress", "chainType", "account", "number", "bank", "mandateId"):
+            if inputs.get(key):
+                safe[key] = inputs[key]
+        for key in ("card", "cardNumber", "expiry", "cvv", "paymentToken"):
+            if inputs.get(key):
+                safe[key] = "[redacted]"
+        return safe
+
+    @classmethod
+    def _settleCheckoutProof(
+        cls,
+        host: Any,
+        *,
+        escrow: dict[str, Any],
+        purchaseIntent: dict[str, Any],
+        candidateRef: dict[str, Any],
+        checkout: dict[str, Any],
+        event: Any,
+    ) -> dict[str, Any]:
+        escrowRecord = escrow.get("escrow", {}) if isinstance(escrow.get("escrow"), dict) else {}
+        escrowId = str(escrowRecord.get("escrowId", "") or "")
+        receipt = checkout.get("receipt", {}) if isinstance(checkout.get("receipt"), dict) else {}
+        receiptId = str(receipt.get("receiptId", "") or "")
+        if not escrowId or not receiptId or not hasattr(host, "submitEscrowProof"):
+            return {}
+        rules = ["sourceBound", "purchaseIntent", "verifiedCompletionProof", "userConfirmedPurchase"]
+        proof = {
+            "proofRef": receiptId,
+            "kind": "checkoutReceipt",
+            "status": "verified",
+            "rules": rules,
+            "source": "bridge.browserCheckout",
+            "payload": {
+                "purchaseIntentId": purchaseIntent.get("intentId", ""),
+                "candidateId": candidateRef.get("candidateId", ""),
+                "source": candidateRef.get("source", ""),
+                "sourceUrl": candidateRef.get("url", ""),
+                "checkout": checkout,
+            },
+        }
+        submitted = host.submitEscrowProof(escrowId, {"proof": proof})
+        event(
+            "pay",
+            "proof.submit",
+            "verified" if submitted.get("ok") else "proofRejected",
+            "PAY received the browser checkout proof and attached it to escrow.",
+            {"escrowId": escrowId, "proofRef": receiptId, "rules": rules},
+        )
+        if not submitted.get("ok"):
+            return {
+                "ok": False,
+                "status": "proofRejected",
+                "reason": str(submitted.get("error", "proofRejected") or "proofRejected"),
+                "proof": proof,
+                "proofSubmission": submitted,
+                "settlementGate": {"status": "locked", "reason": str(submitted.get("error", "proofRejected") or "proofRejected"), "proofRequired": True},
+            }
+        prepared = (
+            host.prepareSettlement({"escrowId": escrowId, "adapter": {"adapterId": "picuxLedgerAdapter", "rail": "picuxLedger", "mode": "execute"}})
+            if hasattr(host, "prepareSettlement")
+            else {}
+        )
+        prepareStatus = "ready" if prepared.get("ok") else "rejected"
+        prepareReason = cls._payFailureReason(prepared)
+        event(
+            "pay",
+            "settlement.prepare",
+            prepareStatus,
+            "PAY prepared settlement from the verified checkout proof." if prepared.get("ok") else f"PAY could not prepare settlement: {prepareReason}.",
+            {"escrowId": escrowId, "settlementId": (prepared.get("instruction", {}) if isinstance(prepared.get("instruction"), dict) else {}).get("settlementId", ""), "errors": cls._payErrors(prepared)},
+        )
+        settlement: dict[str, Any] = {}
+        if prepared.get("ok") and hasattr(host, "settle"):
+            settlement = host.settle({"escrowId": escrowId})
+            event(
+                "pay",
+                "settlement.response",
+                "settled" if settlement.get("ok") else "rejected",
+                "PAY released settlement against the verified checkout proof." if settlement.get("ok") else f"PAY rejected settlement: {cls._payFailureReason(settlement)}.",
+                {"escrowId": escrowId, "receiptId": (settlement.get("receipt", {}) if isinstance(settlement.get("receipt"), dict) else {}).get("receiptId", ""), "errors": cls._payErrors(settlement)},
+            )
+        ok = bool(settlement.get("ok"))
+        reason = "" if ok else prepareReason or cls._payFailureReason(settlement) or "settlementNotReleased"
+        return {
+            "ok": ok,
+            "status": "settled" if ok else "settlementRejected",
+            "reason": reason,
+            "proof": proof,
+            "proofSubmission": submitted,
+            "prepare": prepared,
+            "settlement": settlement,
+            "settlementGate": {"status": "released" if ok else "locked", "reason": "checkoutProofSettled" if ok else reason, "proofRequired": True},
+        }
+
+    @staticmethod
+    def _checkoutNeedsInput(checkout: dict[str, Any]) -> bool:
+        needs = checkout.get("needsInput", []) if isinstance(checkout.get("needsInput"), list) else []
+        return bool(needs) or str(checkout.get("status", "") or "") in {"needsInput", "needsProxy"}
+
+    @staticmethod
+    def _payErrors(result: dict[str, Any]) -> list[str]:
+        if not isinstance(result, dict):
+            return []
+        decision = result.get("decision", {}) if isinstance(result.get("decision"), dict) else {}
+        errors = decision.get("errors", result.get("errors", []))
+        return [str(item) for item in errors if str(item)] if isinstance(errors, list) else ([str(errors)] if str(errors or "") else [])
+
+    @classmethod
+    def _payFailureReason(cls, result: dict[str, Any]) -> str:
+        return ",".join(cls._payErrors(result)) or str(result.get("error", result.get("status", "")) or "")
+
+    @staticmethod
+    def _supportedPaymentMethods() -> list[str]:
+        return ["stripe", "paypal", "card", "bank", "swish", "bitcoin"]
+
+    @classmethod
+    def _paymentSchema(cls) -> dict[str, Any]:
+        return {
+            "methods": [
+                {"method": method, "fields": cls._paymentFieldsFor(method)}
+                for method in cls._supportedPaymentMethods()
+            ]
+        }
+
+    @staticmethod
+    def _paymentFieldsFor(method: str) -> list[str]:
+        return {
+            "stripe": ["account"],
+            "paypal": ["account"],
+            "card": ["cardNumber", "expiry", "cvv"],
+            "bank": ["bank", "account", "number"],
+            "swish": ["number"],
+            "bitcoin": ["walletAddress", "chainType"],
+        }.get(str(method or "").lower(), [])
+
+    @staticmethod
+    def _bridgeNeedsInput(candidateRef: dict[str, Any], missingKeys: list[str]) -> dict[str, Any]:
+        return {
+            "ok": False,
+            "status": "NEEDS_INPUT",
+            "mode": "adapterNeutral",
+            "requestedKeys": missingKeys,
+            "checkout": {
+                "action": "requestInput",
+                "source": candidateRef.get("source", ""),
+                "url": candidateRef.get("url", ""),
+                "candidateId": candidateRef.get("candidateId", ""),
+            },
+        }
+
+    @staticmethod
+    def _isLocalServiceCandidate(candidateRef: dict[str, Any]) -> bool:
+        kind = str(candidateRef.get("kind", "") or "").lower()
+        item = str(candidateRef.get("itemId", "") or "").lower()
+        source = str(candidateRef.get("source", "") or "").lower()
+        return kind == "localservice" or source in {"googleplaces", "openstreetmapnominatim", "clientplaces"} or any(token in item for token in ("mechanic", "plumber", "electrician", "garage", "workshop", "repair"))
+
+    @staticmethod
+    def _originalTaskRequest(task: dict[str, Any]) -> str:
+        inData = task.get("inData", {}) if isinstance(task.get("inData"), dict) else {}
+        return str(inData.get("request", task.get("goal", "")) or "").strip()
+
+    @staticmethod
+    def _localServiceInputs(payload: dict[str, Any], candidateRef: dict[str, Any], *, defaultBrief: str) -> dict[str, Any]:
+        rawInputs = payload.get("inputs") if isinstance(payload.get("inputs"), dict) else {}
+        values = payload.get("values") if isinstance(payload.get("values"), dict) else {}
+        contact = payload.get("contact") if isinstance(payload.get("contact"), dict) else {}
+        inputs = {**rawInputs, **values}
+        return {
+            "userName": payload.get("userName") or inputs.get("userName") or contact.get("name") or "",
+            "userPhone": payload.get("userPhone") or payload.get("phone") or inputs.get("userPhone") or inputs.get("phone") or contact.get("phone") or "",
+            "businessPhone": payload.get("businessPhone") or payload.get("selectedPhone") or inputs.get("businessPhone") or candidateRef.get("phone", "") or "",
+            "issueBrief": payload.get("issueBrief") or payload.get("brief") or inputs.get("issueBrief") or inputs.get("brief") or defaultBrief,
+            "preferredChannel": payload.get("preferredChannel") or inputs.get("preferredChannel") or "whatsapp",
+            "consentToCall": payload.get("consentToCall", inputs.get("consentToCall", payload.get("consent", inputs.get("consent", "")))),
+        }
+
+    @classmethod
+    def _missingLocalServiceKeys(cls, inputs: dict[str, Any], candidateRef: dict[str, Any]) -> list[str]:
+        missing = []
+        if not str(inputs.get("userPhone", "") or "").strip():
+            missing.append("userPhone")
+        if not cls._truthy(inputs.get("consentToCall", "")):
+            missing.append("consentToCall")
+        return missing
+
+    @classmethod
+    def _proxyContactIntent(cls, conversationId: str, taskId: str, candidateRef: dict[str, Any], inputs: dict[str, Any], missingKeys: list[str]) -> dict[str, Any]:
+        intentId = cls._stableId("proxyIntent", {"conversationId": conversationId, "taskId": taskId, "candidateId": candidateRef.get("candidateId", "")})
+        return {
+            "intentId": intentId,
+            "conversationId": conversationId,
+            "taskId": taskId,
+            "status": "needsInput" if missingKeys else "readyForProxy",
+            "candidate": candidateRef,
+            "requestedKeys": missingKeys,
+            "requiredKeys": ["userPhone", "consentToCall"],
+            "channel": str(inputs.get("preferredChannel", "whatsapp") or "whatsapp"),
+            "inputs": {
+                key: value
+                for key, value in {
+                    "userName": inputs.get("userName", ""),
+                    "userPhone": inputs.get("userPhone", ""),
+                    "businessPhone": inputs.get("businessPhone", ""),
+                    "issueBrief": inputs.get("issueBrief", ""),
+                    "preferredChannel": inputs.get("preferredChannel", "whatsapp"),
+                    "consentToCall": bool(cls._truthy(inputs.get("consentToCall", ""))),
+                }.items()
+                if value not in {"", None}
+            },
+        }
+
+    @staticmethod
+    def _truthy(value: Any) -> bool:
+        if isinstance(value, bool):
+            return value
+        return str(value or "").strip().lower() in {"1", "true", "yes", "y", "approved", "approve", "consent", "consented", "ok"}
+
+    @staticmethod
+    def _isLocalServiceRequest(request: str, payload: dict[str, Any], nlp: dict[str, Any]) -> bool:
+        entities = nlp.get("entities", {}) if isinstance(nlp.get("entities"), dict) else {}
+        if str(entities.get("market", "") or "") == "localService":
+            return True
+        if str(payload.get("market", "") or "").lower() in {"localservice", "local_service", "places", "maps"}:
+            return True
+        lowered = request.lower()
+        service = str(entities.get("service", entities.get("entity", "")) or "").lower()
+        placeHints = ("near", "nearby", "within", "around", "close to", "km", "kilometer", "kilometre", "goteborg", "gothenburg", "hisingen", "hisigen")
+        serviceHints = ("mechanic", "plumber", "electrician", "repair", "garage", "workshop", "lawyer", "consultant", "doctor", "dentist", "cleaner", "contractor", "installer", "handyman")
+        return bool(service or any(token in lowered for token in serviceHints)) and any(token in lowered for token in placeHints)
+
+    @classmethod
+    def _placesToOffers(cls, request: str, mapResult: dict[str, Any]) -> list[dict[str, Any]]:
+        places = mapResult.get("places", []) if isinstance(mapResult.get("places"), list) else []
+        query = mapResult.get("query", {}) if isinstance(mapResult.get("query"), dict) else {}
+        itemId = str(query.get("entity", "") or cls._itemId(request) or "localService")
+        offers = []
+        for index, place in enumerate(places[:10], start=1):
+            if not isinstance(place, dict):
+                continue
+            name = str(place.get("name", "") or "").strip()
+            if not name:
+                continue
+            source = str(place.get("source", mapResult.get("provider", "mapTool")) or "mapTool")
+            sourceUrl = str(place.get("sourceUrl", "") or "")
+            placeId = str(place.get("placeId", "") or "")
+            candidateId = placeId if placeId.startswith("place_") else cls._stableId("place", {"placeId": placeId, "name": name, "source": source, "sourceUrl": sourceUrl})
+            contactRef = cls._contactRefForPlace(place, candidateId)
+            rating = cls._float(place.get("rating", 0.0))
+            distanceKm = cls._float(place.get("distanceKm", 0.0))
+            stock = 1 if bool(place.get("sourceBound")) else 0
+            offers.append(
+                {
+                    "sourceId": candidateId,
+                    "candidateId": candidateId,
+                    "itemId": itemId,
+                    "listUsd": 0.0,
+                    "offerUsd": 0.0,
+                    "feesUsd": 0.0,
+                    "stock": stock,
+                    "meta": {
+                        "kind": "localService",
+                        "placeKind": "localService",
+                        "reader": "mapTool",
+                        "source": source,
+                        "sourceUrl": sourceUrl,
+                        "listingTitle": name,
+                        "address": str(place.get("address", "") or ""),
+                        "website": str(place.get("website", "") or ""),
+                        "rating": rating,
+                        "distanceKm": distanceKm,
+                        "placeId": placeId,
+                        "contactRef": contactRef,
+                        "contactStatus": "private",
+                        "verified": bool(place.get("verified")),
+                        "placeIndex": index,
+                        "entity": itemId,
+                        "price": {},
+                        "sourceBound": bool(place.get("sourceBound")),
+                    },
+                }
+            )
+        return offers
+
+    @classmethod
+    def _contactRefForPlace(cls, place: dict[str, Any], candidateId: str) -> str:
+        explicit = str(place.get("contactRef", "") or "")
+        if explicit:
+            return explicit
+        return cls._stableId(
+            "localContact",
+            {
+                "candidateId": candidateId,
+                "placeId": str(place.get("placeId", "") or ""),
+                "name": str(place.get("name", "") or ""),
+                "source": str(place.get("source", "") or ""),
+            },
+        )
+
+    @staticmethod
+    def _mapBrowserTelemetry(mapResult: dict[str, Any], offers: list[dict[str, Any]], *, country: str) -> dict[str, Any]:
+        provider = str(mapResult.get("provider", "mapTool") or "mapTool")
+        query = mapResult.get("query", {}) if isinstance(mapResult.get("query"), dict) else {}
+        places = mapResult.get("places", []) if isinstance(mapResult.get("places"), list) else []
+        ok = bool(places) or str(mapResult.get("status", "") or "") == "searchedNoPlaces"
+        search = {
+            "mode": "placesSearch",
+            "query": " ".join(str(query.get(key, "") or "") for key in ("entity", "location")).strip(),
+            "submitted": bool(mapResult.get("networkAttempted") or places),
+            "radiusKm": query.get("radiusKm", 0),
+        }
+        return {
+            "adapter": provider,
+            "rendered": {},
+            "marketplaceSet": {
+                "market": "localService",
+                "country": country.lower(),
+                "sources": [provider],
+                "localSources": [provider],
+                "entity": str(query.get("entity", "") or ""),
+                "location": str(query.get("location", "") or ""),
+                "radiusKm": query.get("radiusKm", 0),
+            },
+            "budget": {},
+            "fx": {},
+            "networkAttempted": bool(mapResult.get("networkAttempted")),
+            "searchTargets": [{"source": provider, "url": "googlePlaces://textSearch" if provider == "googlePlaces" else provider, "kind": "placesSearch"}],
+            "marketplaceAttempts": [
+                {
+                    "source": provider,
+                    "url": "googlePlaces://textSearch" if provider == "googlePlaces" else provider,
+                    "ok": ok,
+                    "adapter": provider,
+                    "statusCode": 200 if ok else 0,
+                    "title": f"{query.get('entity', 'places')} near {query.get('location', '')}".strip(),
+                    "matched": ok,
+                    "listingCount": len(places),
+                    "filteredListingCount": len(offers),
+                    "search": search,
+                    "error": "; ".join(str(item) for item in mapResult.get("errors", []) if item),
+                }
+            ],
+            "observations": [
+                {
+                    "source": provider,
+                    "url": "googlePlaces://textSearch" if provider == "googlePlaces" else provider,
+                    "ok": ok,
+                    "adapter": provider,
+                    "statusCode": 200 if ok else 0,
+                    "title": f"{query.get('entity', 'places')} near {query.get('location', '')}".strip(),
+                    "matched": ok,
+                    "listingCount": len(places),
+                    "search": search,
+                    "error": "; ".join(str(item) for item in mapResult.get("errors", []) if item),
+                }
+            ],
+            "offers": offers,
+            "errors": [] if ok else [{"source": provider, "ok": False, "error": "; ".join(str(item) for item in mapResult.get("errors", []) if item)}],
+            "status": str(mapResult.get("status", "")),
+        }
+
+    @staticmethod
+    def _float(value: Any) -> float:
+        try:
+            return float(value or 0.0)
+        except Exception:
+            return 0.0
+
+    def _huntPayload(self, request: str, payload: dict[str, Any], *, taskId: str, browser: dict[str, Any] | None = None, clientId: str = "orchestrator", channel: str = "api") -> dict[str, Any]:
+        criteria = payload.get("criteria") if isinstance(payload.get("criteria"), dict) else {}
+        budget = self._budget(request, payload)
+        itemId = str(criteria.get("itemId", "") or self._itemId(request) or "requestedItem")
+        maxNetUsd = float(criteria.get("maxNetUsd", budget) or budget or 0.0)
+        rawOffers = payload.get("offers", payload.get("telemetry", []))
+        offers = rawOffers if isinstance(rawOffers, list) else []
+        browser = browser or {}
+        browserOffers = browser.get("offers", []) if isinstance(browser.get("offers"), list) else []
+        if not offers and browserOffers:
+            offers = browserOffers
+        return {
+            "taskId": taskId,
+            "criteria": {
+                "itemId": itemId,
+                "minDiscountPct": float(criteria.get("minDiscountPct")) if "minDiscountPct" in criteria else 0.0,
+                "maxNetUsd": maxNetUsd,
+                "minStock": int(criteria.get("minStock", 1) or 1),
+                "region": str(criteria.get("region", "") or ""),
+            },
+            "telemetry": offers,
+            "sourceTelemetry": self._sourceTelemetry(browser),
+            "handoff": self._handoff(payload, clientId, channel),
+        }
+
+    @staticmethod
+    def _sourceTelemetry(browser: dict[str, Any]) -> dict[str, Any]:
+        attempts = browser.get("marketplaceAttempts", []) if isinstance(browser.get("marketplaceAttempts"), list) else []
+        targets = browser.get("searchTargets", []) if isinstance(browser.get("searchTargets"), list) else []
+        return {
+            "adapter": browser.get("adapter", ""),
+            "rendered": browser.get("rendered", {}),
+            "marketplaceSet": browser.get("marketplaceSet", {}),
+            "budget": browser.get("budget", {}),
+            "fx": browser.get("fx", {}),
+            "networkAttempted": bool(browser.get("networkAttempted")),
+            "targetSources": [item.get("source", "") for item in targets if isinstance(item, dict)],
+            "attempts": attempts,
+            "observations": PicuxMultiAgentOrchestrator._sourceObservationSummaries(browser),
+            "offerCount": len(browser.get("offers", [])) if isinstance(browser.get("offers"), list) else 0,
+            "observationCount": len(browser.get("observations", [])) if isinstance(browser.get("observations"), list) else 0,
+            "status": browser.get("status", ""),
+        }
+
+    @staticmethod
+    def _sourceObservationSummaries(browser: dict[str, Any]) -> list[dict[str, Any]]:
+        observations = browser.get("observations", []) if isinstance(browser.get("observations"), list) else []
+        summaries = []
+        for observation in observations:
+            if not isinstance(observation, dict):
+                continue
+            listings = observation.get("listings", []) if isinstance(observation.get("listings"), list) else []
+            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(listings),
+                    "search": observation.get("search", {}) if isinstance(observation.get("search"), dict) else {},
+                    "error": observation.get("error", ""),
+                }
+            )
+        return summaries
+
+    @staticmethod
+    def _handoff(payload: dict[str, Any], clientId: str, channel: str) -> dict[str, str]:
+        raw = payload.get("handoff", payload.get("handsoff", {}))
+        raw = raw if isinstance(raw, dict) else {}
+        explicitSource = raw.get("source") or payload.get("handoffSource") or payload.get("handsoffSource")
+        source = str(explicitSource or clientId or "externalClient")
+        explicitTarget = raw.get("target") or payload.get("handoffTarget") or payload.get("handsoffTarget")
+        target = str(explicitTarget or (source if explicitSource else "orchestrator") or "orchestrator")
+        if target in {"source", "handoffSource", "handsoffSource"}:
+            target = source
+        return {
+            "source": source,
+            "target": target,
+            "channel": str(raw.get("channel", payload.get("handoffChannel", channel)) or channel),
+            "mode": str(raw.get("mode", payload.get("handoffMode", "return")) or "return"),
+        }
+
+    @staticmethod
+    def _decisionTree(hunt: dict[str, Any]) -> dict[str, Any]:
+        candidates = hunt.get("candidates", []) if isinstance(hunt.get("candidates"), list) else []
+        selected = hunt.get("selected", {}) if isinstance(hunt.get("selected"), dict) else {}
+        paths = []
+        for item in candidates:
+            if not isinstance(item, dict):
+                continue
+            sourceId = str(item.get("sourceId", "") or "")
+            candidateId = str(item.get("candidateId", "") or sourceId)
+            meta = item.get("meta", {}) if isinstance(item.get("meta"), dict) else {}
+            price = meta.get("price", {}) if isinstance(meta.get("price"), dict) else {}
+            paths.append(
+                {
+                    "candidateId": candidateId,
+                    "vendorId": sourceId,
+                    "source": str(meta.get("source", "") or ""),
+                    "title": str(meta.get("listingTitle", item.get("itemId", "")) or ""),
+                    "url": str(meta.get("sourceUrl", "") or ""),
+                    "kind": str(meta.get("kind", meta.get("placeKind", "")) or ""),
+                    "address": str(meta.get("address", "") or ""),
+                    "website": str(meta.get("website", "") or ""),
+                    "rating": meta.get("rating", 0),
+                    "distanceKm": meta.get("distanceKm", 0),
+                    "price": price,
+                    "status": "selected" if selected.get("sourceId") == sourceId else "pruned",
+                    "reasons": item.get("reasons", []) if isinstance(item.get("reasons"), list) else [],
+                    "netUsd": item.get("netUsd", 0),
+                }
+            )
+        return {"root": "userRequest", "selected": str(selected.get("sourceId", "") or ""), "paths": paths}
+
+    @staticmethod
+    def _itemId(request: str) -> str:
+        match = re.search(r"\b(i\s*phone\s*\d+|iphone\s*\d+|iphone|smartphone|phone|tv|laptop|car|apartment|house|property|mechanic|lead|option)\b", request, re.IGNORECASE)
+        if match:
+            return re.sub(r"\s+", "", match.group(1).lower())
+        subject = re.search(
+            r"\b(?:buy|find|get|search(?: for)?|shop(?: for)?|source)\s+(?:a|an|the|my)?\s*(.+?)(?:\s+(?:under|less than|below|budget|for)\b|\s+(?:in|near|around)\s+[A-Z][A-Za-z]+|$)",
+            request,
+            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]
+        words = [word for word in re.findall(r"[A-Za-z0-9]+", request) if len(word) > 2]
+        return words[0].lower() if words else "requestedItem"
+
+    @staticmethod
+    def _conversationItemLabel(request: str) -> str:
+        itemId = PicuxMultiAgentOrchestrator._itemId(request)
+        if itemId and itemId != "requestedItem":
+            return PicuxMultiAgentOrchestrator._displayItem(itemId)
+        subject = re.search(
+            r"\b(?:buy|find|get|search(?: for)?|shop(?: for)?|source)\s+(?:a|an|the|my)?\s*(.+?)(?:\s+(?:under|less than|below|budget|for)\b|\s+(?:in|near|around)\s+[A-Z][A-Za-z]+|$)",
+            request,
+            re.IGNORECASE,
+        )
+        if not subject:
+            return "matching options"
+        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()
+        return clean[:80] or "matching options"
+
+    @classmethod
+    def _huntConversationSummary(cls, request: str, hunt: dict[str, Any]) -> str:
+        sourceResponse = hunt.get("sourceResponse", {}) if isinstance(hunt.get("sourceResponse"), dict) else {}
+        aggregate = hunt.get("sourceAggregate", {}) if isinstance(hunt.get("sourceAggregate"), dict) else {}
+        sources = aggregate.get("sources", []) if isinstance(aggregate.get("sources"), list) else []
+        candidates = hunt.get("candidates", []) if isinstance(hunt.get("candidates"), list) else []
+        offers = aggregate.get("offers", []) if isinstance(aggregate.get("offers"), list) else []
+        label = cls._conversationItemLabel(request)
+        marketplaceSet = sourceResponse.get("marketplaceSet", {}) if isinstance(sourceResponse.get("marketplaceSet"), dict) else {}
+        localService = str(marketplaceSet.get("market", "") or "") == "localService"
+        resultSources = cls._resultSources(candidates, offers, sources)
+        if candidates:
+            if localService:
+                entity = str(marketplaceSet.get("entity", "") or label or "local service")
+                location = str(marketplaceSet.get("location", "") or "").strip()
+                noun = cls._pluralService(entity)
+                line = f"Found {len(candidates)} {noun}"
+                if location:
+                    line += f" in {location}"
+                return line + "."
+            top = cls._topListingSummaries(candidates)
+            sourceText = cls._sourceList(resultSources)
+            listingWord = ("place" if len(candidates) == 1 else "places") if localService else ("listing" if len(candidates) == 1 else "listings")
+            line = f"Found {len(candidates)} source-bound {label} {listingWord}"
+            if sourceText:
+                marketWord = "map source" if localService and len(resultSources) == 1 else ("map sources" if localService else ("marketplace" if len(resultSources) == 1 else "marketplaces"))
+                line += f" from {len(resultSources)} {marketWord}: {sourceText}"
+            if top:
+                line += f". Top matches: {'; '.join(top)}"
+            return line + "."
+        listingSources = [source for source in sources if int(source.get("listingCount", 0) or 0) > 0]
+        if listingSources:
+            listingCount = sum(int(source.get("listingCount", 0) or 0) for source in listingSources)
+            sourceText = cls._sourceList([str(source.get("source", "") or "") for source in listingSources])
+            return f"Found {listingCount} raw {label} listings on {sourceText}, but none passed the model, price, and evidence filters yet."
+        attempted = sourceResponse.get("attemptedSources", []) if isinstance(sourceResponse.get("attemptedSources"), list) else []
+        failed = sourceResponse.get("failedSources", []) if isinstance(sourceResponse.get("failedSources"), list) else []
+        if attempted:
+            sourceText = cls._sourceList([str(source) for source in attempted])
+            if len(failed) == len(attempted):
+                return f"Searched {sourceText}, but every source returned an I/O error or blocked page."
+            if localService:
+                return f"Searched {sourceText}, but no source returned a source-bound {label} place yet."
+            return f"Searched {sourceText}, but no source returned a price-bound {label} listing yet."
+        targets = sourceResponse.get("targetSources", []) if isinstance(sourceResponse.get("targetSources"), list) else []
+        if targets:
+            return f"Prepared {len(targets)} source targets for {label}: {cls._sourceList([str(source) for source in targets])}."
+        return ""
+
+    @staticmethod
+    def _pluralService(entity: str) -> str:
+        clean = re.sub(r"\s+", " ", str(entity or "local service").strip().lower())
+        if clean in {"mechanic", "car repair", "bilverkstad"}:
+            return "mechanics"
+        if clean.endswith("s"):
+            return clean
+        if clean.endswith("y"):
+            return clean[:-1] + "ies"
+        return clean + "s"
+
+    @staticmethod
+    def _resultSources(candidates: list[Any], offers: list[Any], sources: list[Any]) -> list[str]:
+        result: list[str] = []
+        for item in [*candidates, *offers]:
+            if not isinstance(item, dict):
+                continue
+            meta = item.get("meta", {}) if isinstance(item.get("meta"), dict) else {}
+            source = str(meta.get("source", "") or "")
+            if source:
+                result.append(source)
+        if result:
+            return list(dict.fromkeys(result))
+        return list(
+            dict.fromkeys(
+                str(source.get("source", "") or "")
+                for source in sources
+                if isinstance(source, dict) and int(source.get("listingCount", 0) or 0) > 0
+            )
+        )
+
+    @classmethod
+    def _topListingSummaries(cls, candidates: list[Any]) -> list[str]:
+        summaries = []
+        ordered = [item for item in candidates if isinstance(item, dict)]
+        ordered.sort(key=lambda item: (not bool(item.get("eligible")), float(item.get("netUsd", item.get("offerUsd", 0.0)) or 0.0)))
+        for item in ordered[:3]:
+            meta = item.get("meta", {}) if isinstance(item.get("meta"), dict) else {}
+            title = str(meta.get("listingTitle", "") or item.get("itemId", "") or "listing").strip()
+            source = cls._displaySource(str(meta.get("source", "") or ""))
+            price = meta.get("price", {}) if isinstance(meta.get("price"), dict) else {}
+            priceText = cls._formatPrice(price, float(item.get("netUsd", item.get("offerUsd", 0.0)) or 0.0))
+            reasons = item.get("reasons", []) if isinstance(item.get("reasons"), list) else []
+            suffix = ""
+            if reasons:
+                suffix = f" ({', '.join(str(reason) for reason in reasons[:2])})"
+            summary = f"{title}"
+            if priceText:
+                summary += f" - {priceText}"
+            if source:
+                summary += f" on {source}"
+            summaries.append(summary + suffix)
+        return summaries
+
+    @staticmethod
+    def _formatPrice(price: dict[str, Any], usd: float) -> str:
+        amount = price.get("amount")
+        currency = str(price.get("currency", "") or "").upper()
+        if amount and currency:
+            try:
+                amountText = f"{float(amount):,.0f}" if float(amount).is_integer() else f"{float(amount):,.2f}"
+            except Exception:
+                amountText = str(amount)
+            if currency == "USD":
+                return f"${amountText}"
+            return f"{amountText} {currency} (about ${usd:,.0f})"
+        if usd > 0:
+            return f"about ${usd:,.0f}"
+        return ""
+
+    @staticmethod
+    def _sourceList(sources: list[str]) -> str:
+        names = [PicuxMultiAgentOrchestrator._displaySource(source) for source in sources if source]
+        return ", ".join(list(dict.fromkeys(name for name in names if name))[:8])
+
+    @staticmethod
+    def _displaySource(source: str) -> str:
+        labels = {
+            "blocket": "Blocket",
+            "tradera": "Tradera",
+            "facebook": "Facebook Marketplace",
+            "ebay": "eBay",
+            "alibaba": "Alibaba",
+            "amazon": "Amazon",
+            "shopify": "Shop",
+            "jumia": "Jumia",
+            "konga": "Konga",
+            "jiji": "Jiji",
+            "googleplaces": "Google Places",
+            "openstreetmapnominatim": "OpenStreetMap",
+            "clientplaces": "Client Places",
+        }
+        return labels.get(source.lower(), source)
+
+    @staticmethod
+    def _displayItem(itemId: str) -> str:
+        compact = re.sub(r"\s+", "", str(itemId or "")).lower()
+        phone = re.match(r"iphone(\d+)$", compact)
+        if phone:
+            return f"iPhone {phone.group(1)}"
+        if compact == "iphone":
+            return "iPhone"
+        if compact == "smartphone":
+            return "smartphone"
+        if compact == "tv":
+            return "TV"
+        return re.sub(r"\s+", " ", str(itemId or "")).strip()
+
+    @staticmethod
+    def _budget(request: str, payload: dict[str, Any]) -> float:
+        raw = payload.get("budget", payload.get("maxSpend", 0))
+        try:
+            if raw:
+                return float(raw)
+        except Exception:
+            pass
+        patterns = (
+            r"(?:under|less than|below|budget|for)\s*\$?\s*([0-9]+(?:\.[0-9]{1,2})?)",
+            r"\$\s*([0-9]+(?:\.[0-9]{1,2})?)",
+            r"\b([0-9]+(?:\.[0-9]{1,2})?)\s*(?:dollar|usd)\b",
+        )
+        for pattern in patterns:
+            match = re.search(pattern, request, re.IGNORECASE)
+            if not match:
+                continue
+            try:
+                return float(match.group(1))
+            except Exception:
+                return 0.0
+        return 0.0
+
+    @classmethod
+    def _startResolveRecovery(
+        cls,
+        host: Any,
+        *,
+        request: str,
+        payload: dict[str, Any],
+        target: dict[str, Any],
+        documents: list[Any],
+        taskId: str,
+        conversationId: str,
+    ) -> dict[str, Any]:
+        if not target or not hasattr(host, "resolveRecovery"):
+            return {}
+        if hasattr(host, "_ensureReadyConnectors"):
+            try:
+                host._ensureReadyConnectors()
+            except Exception:
+                pass
+        recoveryPayload = {
+            **payload,
+            "claim": request,
+            "text": request,
+            "taskId": taskId,
+            "conversationId": conversationId,
+            "targetEntity": target,
+            "attachments": documents,
+            "request": {
+                "issueType": cls._issueType(request),
+                "attachments": documents,
+                **(payload.get("request", {}) if isinstance(payload.get("request"), dict) else {}),
+            },
+        }
+        try:
+            result = host.resolveRecovery(recoveryPayload)
+        except Exception as exc:
+            return {"ok": False, "status": "blocked", "reason": type(exc).__name__}
+        recovery = result.get("recovery", {}) if isinstance(result.get("recovery"), dict) else {}
+        if not recovery:
+            return {}
+        return {
+            **recovery,
+            "taskId": str(result.get("taskId", taskId) or taskId),
+            "case": result.get("case", {}) if isinstance(result.get("case"), dict) else {},
+            "proofCard": result.get("proofCard", {}) if isinstance(result.get("proofCard"), dict) else {},
+        }
+
+    @classmethod
+    def _target(cls, request: str, payload: dict[str, Any]) -> dict[str, Any]:
+        target = payload.get("target") if isinstance(payload.get("target"), dict) else payload.get("targetEntity", {})
+        if isinstance(target, dict) and target:
+            return target
+        lowered = request.lower()
+        if "bank" in lowered:
+            return {"entityId": "bank", "name": "bank", "type": "bank"}
+        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", request, re.IGNORECASE)
+        if domainMerchant:
+            name = domainMerchant.group(1).strip()
+            return {"entityId": cls._stableId("entity", {"name": name}), "name": name, "type": "merchant"}
+        merchant = re.search(r"\bfrom\s+([A-Z][A-Za-z0-9.& -]{2,40})", request)
+        if merchant:
+            name = merchant.group(1).strip()
+            return {"entityId": cls._stableId("entity", {"name": name}), "name": name, "type": "merchant"}
+        if any(token in lowered for token in ("merchant", "shop", "store", "support")):
+            return {"entityId": "merchant", "name": "merchant support", "type": "merchant"}
+        return {}
+
+    @staticmethod
+    def _preferredChannel(request: str) -> str:
+        lowered = request.lower()
+        if "email" in lowered:
+            return "email"
+        if "chat" in lowered or "whatsapp" in lowered:
+            return "chat"
+        if "phone" in lowered or "call" in lowered:
+            return "phone"
+        return ""
+
+    @staticmethod
+    def _issueType(request: str) -> str:
+        lowered = request.lower()
+        if "broken" in lowered or "damaged" in lowered:
+            return "damaged goods claim"
+        if "fake" in lowered or "scam" in lowered:
+            return "scam or fake offer claim"
+        if "used" in lowered:
+            return "used item verification"
+        return "consumer claim"
+
+    @classmethod
+    def _hasPhone(cls, request: str, payload: dict[str, Any]) -> bool:
+        return bool(cls._phone(request, payload))
+
+    @staticmethod
+    def _phone(request: 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", request)
+        return match.group(0).strip() if match else ""
+
+    @staticmethod
+    def _shouldCreateProxy(request: str, payload: dict[str, Any]) -> bool:
+        if bool(payload.get("requiresProxy", payload.get("humanRequired", False))):
+            return True
+        lowered = request.lower()
+        return any(
+            token in lowered
+            for token in (
+                "place a call",
+                "make a call",
+                "call merchant",
+                "call support",
+                "human handoff",
+                "manual review",
+                "lawyer",
+                "consultant",
+                "customer representative",
+                "customer represent",
+                "representative",
+                "followup",
+                "follow up",
+                "did not follow",
+                "no response",
+                "logistics",
+                "pickup",
+                "delivery",
+            )
+        )
+
+    @staticmethod
+    def _isResolveCase(request: str) -> bool:
+        lowered = str(request 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
+
+    @staticmethod
+    def _stableId(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]}"