patchr 0.1.0__py3-none-any.whl

picux/domains/bridge/HostRun.py

@@ -0,0 +1,1104 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import smtplib
+import ssl
+from datetime import datetime, timezone
+from email.message import EmailMessage
+from html import escape
+from typing import Any
+from urllib import error, parse, request
+
+from picux.security import SecretResolver
+
+
+class HostedBridgeAdapters:
+    """Execute Picux-hosted Bridge adapters with client-registered credentials."""
+
+    def __init__(self, *, secrets: SecretResolver | None = None, timeoutSeconds: int = 15) -> None:
+        self.secrets = secrets or SecretResolver()
+        self.timeoutSeconds = timeoutSeconds
+
+    def run(
+        self,
+        action: dict[str, Any],
+        connector: dict[str, Any],
+        session: dict[str, Any],
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        kind = self._kind(action, connector, session, payload)
+        if kind == "gmail":
+            return self._gmail(action, connector, session, payload)
+        if kind == "googleDocs":
+            return self._googleDocs(action, connector, session, payload)
+        if kind == "notion":
+            return self._notion(action, connector, session, payload)
+        if kind == "jira":
+            return self._jira(action, connector, session, payload)
+        if kind == "salesforce":
+            return self._salesforce(action, connector, session, payload)
+        if kind == "hubspot":
+            return self._hubspot(action, connector, session, payload)
+        if kind == "zendesk":
+            return self._zendesk(action, connector, session, payload)
+        if kind == "sap":
+            return self._sap(action, connector, session, payload)
+        if kind == "twilioVoice":
+            return self._twilioVoice(action, connector, session, payload)
+        if kind == "whatsapp":
+            return self._whatsapp(action, connector, session, payload)
+        if kind == "slack":
+            return self._slack(action, connector, session, payload)
+        if kind == "smtp":
+            return self._smtp(action, connector, session, payload)
+        if kind == "httpJson":
+            return self._httpJson(action, connector, session, payload)
+        return {}
+
+    def _kind(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> str:
+        meta = connector.get("meta", {}) if isinstance(connector.get("meta"), dict) else {}
+        endpoint = str(connector.get("endpoint", "") or "")
+        caps = " ".join(str(item or "") for item in connector.get("caps", []) if str(item))
+        parts = [
+            action.get("connectorId", ""),
+            action.get("action", ""),
+            action.get("resource", ""),
+            action.get("channel", ""),
+            action.get("provider", ""),
+            connector.get("connectorId", ""),
+            connector.get("kind", ""),
+            connector.get("name", ""),
+            endpoint,
+            caps,
+            meta.get("provider", ""),
+            payload.get("adapter", ""),
+            payload.get("tool", ""),
+        ]
+        needle = " ".join(str(item or "") for item in parts).lower()
+        if "notion" in needle and ("docs.write" in needle or "page" in needle or "casefile" in needle or "knowledge" in needle):
+            return "notion"
+        if "jira" in needle or "atlassian" in needle:
+            return "jira"
+        if "salesforce" in needle or "crm.cases" in needle or "case.write" in needle:
+            return "salesforce"
+        if "hubspot" in needle:
+            return "hubspot"
+        if "zendesk" in needle:
+            return "zendesk"
+        if "bridge://sap" in needle or " sap " in f" {needle} " or "sap." in needle or "erp" in needle:
+            return "sap"
+        if "gmail" in needle and ("email.send" in needle or "messages.send" in needle or action.get("channel") == "email"):
+            return "gmail"
+        if "googledocs" in needle or "google-docs" in needle or (
+            ("google" in needle or "gdocs" in needle) and ("docs.write" in needle or "documents.write" in needle)
+        ):
+            return "googleDocs"
+        if "twilio" in needle or "voice.call" in needle or "call.create" in needle:
+            return "twilioVoice"
+        if "whatsapp" in needle:
+            return "whatsapp"
+        if "slack" in needle:
+            return "slack"
+        if ("email.send" in needle or action.get("channel") == "email") and self._env(("PICUX_SMTP_HOST", "SMTP_HOST"))[0]:
+            return "smtp"
+        if endpoint.startswith(("http://", "https://")) and self._shouldRunHttp(connector, session, payload):
+            return "httpJson"
+        return ""
+
+    def _shouldRunHttp(self, connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> bool:
+        return self._hostedRequired(connector, session, payload)
+
+    @staticmethod
+    def _hostedRequired(connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> bool:
+        meta = connector.get("meta", {}) if isinstance(connector.get("meta"), dict) else {}
+        mode = str(session.get("executionMode", "") or meta.get("executionMode", "") or "")
+        return bool(
+            mode in {"picuxHostedAdapter", "hostedAdapter", "picuxHosted", "hosted"}
+            or meta.get("hostedAdapter")
+            or meta.get("picuxHostedAdapter")
+            or payload.get("executeHosted")
+            or payload.get("runHosted")
+            or payload.get("hostedAdapter")
+        )
+
+    def _httpJson(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        endpoint = str(connector.get("endpoint", "") or "")
+        if not endpoint.startswith(("http://", "https://")):
+            return {}
+        body = {
+            "action": self._actionRef(action),
+            "connector": self._connectorRef(connector),
+            "session": self._sessionRef(session),
+            "payload": payload,
+            "createdAt": self._now(),
+        }
+        headers = {"X-Picux-Bridge-Action": str(action.get("actionId", "") or "")}
+        token = self._credentialToken(connector, session)
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        status, responseBody, errText = self._postJson(endpoint, body, headers=headers)
+        providerRef = str(responseBody.get("id", responseBody.get("messageId", responseBody.get("providerRef", ""))) or "")
+        ok = 200 <= status < 300
+        result = {
+            "ok": ok,
+            "status": "sent" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": providerRef or self._stableId("bridgeHttp", {"actionId": action.get("actionId", ""), "status": status, "body": responseBody}),
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        return self._adapterResult("httpJson", action, connector, result, endpoint=endpoint)
+
+    def _gmail(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._bearerToken(connector, session, ("GMAIL_ACCESS_TOKEN", "GOOGLE_GMAIL_ACCESS_TOKEN", "GOOGLE_ACCESS_TOKEN"))
+        toEmail = self._email(payload)
+        if not token:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("gmail", action, connector, "missingBridgeCredentials", missingEnv=["GMAIL_ACCESS_TOKEN"])
+        if not toEmail:
+            return self._blocked("gmail", action, connector, "missingDestinationEmail", missingEnv=[])
+        userId = str(payload.get("userId", payload.get("gmailUserId", "me")) or "me")
+        baseUrl = self._providerUrl(connector, session, payload, "gmailBaseUrl", "https://gmail.googleapis.com").rstrip("/")
+        endpoint = f"{baseUrl}/gmail/v1/users/{parse.quote(userId)}/messages/send"
+        raw = self._gmailRaw(payload, toEmail)
+        status, responseBody, errText = self._postJson(endpoint, {"raw": raw}, headers={"Authorization": f"Bearer {token}"})
+        ok = 200 <= status < 300
+        result = {
+            "ok": ok,
+            "status": "sent" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": str(responseBody.get("id", responseBody.get("messageId", "")) or self._stableId("gmailMsg", {"actionId": action.get("actionId", ""), "to": toEmail})),
+            "channel": "email",
+            "toRef": self._redactEmail(toEmail),
+            "credentialRefs": [tokenKey],
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        return self._adapterResult("gmail", action, connector, result, endpoint=endpoint)
+
+    def _googleDocs(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._bearerToken(connector, session, ("GOOGLE_DOCS_ACCESS_TOKEN", "GOOGLE_ACCESS_TOKEN"))
+        if not token:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("googleDocs", action, connector, "missingBridgeCredentials", missingEnv=["GOOGLE_DOCS_ACCESS_TOKEN"])
+        baseUrl = self._providerUrl(connector, session, payload, "googleDocsBaseUrl", "https://docs.googleapis.com").rstrip("/")
+        title = str(payload.get("title", payload.get("subject", "Picux case document")) or "Picux case document")
+        text = self._message(payload, fallback=str(payload.get("content", "") or ""))
+        createEndpoint = f"{baseUrl}/v1/documents"
+        status, responseBody, errText = self._postJson(createEndpoint, {"title": title}, headers={"Authorization": f"Bearer {token}"})
+        docId = str(responseBody.get("documentId", responseBody.get("id", "")) or "")
+        batchStatus = 0
+        batchResponse: dict[str, Any] = {}
+        batchError = ""
+        if 200 <= status < 300 and docId and text:
+            batchEndpoint = f"{baseUrl}/v1/documents/{parse.quote(docId)}:batchUpdate"
+            batchStatus, batchResponse, batchError = self._postJson(
+                batchEndpoint,
+                {"requests": [{"insertText": {"location": {"index": 1}, "text": text}}]},
+                headers={"Authorization": f"Bearer {token}"},
+            )
+        ok = 200 <= status < 300 and (not text or 200 <= batchStatus < 300)
+        reason = "" if ok else batchError or errText or f"httpStatus:{batchStatus or status}"
+        result = {
+            "ok": ok,
+            "status": "created" if ok else "ioError",
+            "providerStatus": batchStatus or status,
+            "providerRef": docId or self._stableId("googleDoc", {"actionId": action.get("actionId", ""), "title": title}),
+            "channel": "document",
+            "documentId": docId,
+            "credentialRefs": [tokenKey],
+            "response": {"create": responseBody, "batchUpdate": batchResponse},
+            "reason": reason,
+        }
+        source = f"https://docs.google.com/document/d/{docId}" if docId else createEndpoint
+        return self._adapterResult("googleDocs", action, connector, result, endpoint=source)
+
+    def _notion(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._bearerToken(connector, session, ("NOTION_TOKEN", "PICUX_NOTION_TOKEN"))
+        databaseId, databaseKey = self._fieldValue(
+            connector,
+            session,
+            payload,
+            ("databaseId", "notionDatabaseId", "NOTION_DATABASE_ID", "PICUX_NOTION_DATABASE_ID"),
+            ("NOTION_DATABASE_ID", "PICUX_NOTION_DATABASE_ID"),
+        )
+        if not token:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("notion", action, connector, "missingBridgeCredentials", missingEnv=["NOTION_TOKEN"])
+        if not databaseId:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("notion", action, connector, "missingNotionDatabaseId", missingEnv=["NOTION_DATABASE_ID"])
+        baseUrl = self._providerUrl(connector, session, payload, "notionBaseUrl", "https://api.notion.com").rstrip("/")
+        endpoint = f"{baseUrl}/v1/pages"
+        title = str(payload.get("title", payload.get("subject", "Picux case file")) or "Picux case file")
+        body = self._message(payload, fallback=str(payload.get("content", "") or ""))
+        statusName = str(payload.get("statusName", payload.get("status", "Open")) or "Open")
+        requestBody = {
+            "parent": {"database_id": databaseId},
+            "properties": {
+                "Name": {"title": [{"text": {"content": title[:2000]}}]},
+                "Status": {"select": {"name": statusName[:100]}},
+            },
+            "children": [{"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"type": "text", "text": {"content": body[:2000]}}]}}],
+        }
+        status, responseBody, errText = self._postJson(
+            endpoint,
+            requestBody,
+            headers={"Authorization": f"Bearer {token}", "Notion-Version": str(payload.get("notionVersion", "2022-06-28") or "2022-06-28")},
+        )
+        ok = 200 <= status < 300
+        pageId = str(responseBody.get("id", "") or "")
+        result = {
+            "ok": ok,
+            "status": "created" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": pageId or self._stableId("notionPage", {"actionId": action.get("actionId", ""), "title": title}),
+            "channel": "workspace",
+            "credentialRefs": [tokenKey, databaseKey],
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        source = str(responseBody.get("url", endpoint) or endpoint)
+        return self._adapterResult("notion", action, connector, result, endpoint=source)
+
+    def _jira(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        baseUrl = self._providerUrl(connector, session, payload, "jiraBaseUrl", "").rstrip("/") or self._env(("JIRA_BASE_URL", "ATLASSIAN_BASE_URL"))[0].rstrip("/")
+        authHeader, authRef = self._jiraAuth(connector, session)
+        projectKey, projectKeyRef = self._fieldValue(
+            connector,
+            session,
+            payload,
+            ("projectKey", "jiraProjectKey", "JIRA_PROJECT_KEY", "PICUX_JIRA_PROJECT_KEY"),
+            ("JIRA_PROJECT_KEY", "PICUX_JIRA_PROJECT_KEY"),
+        )
+        if not baseUrl:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("jira", action, connector, "missingJiraBaseUrl", missingEnv=["JIRA_BASE_URL"])
+        if not authHeader:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("jira", action, connector, "missingBridgeCredentials", missingEnv=["JIRA_ACCESS_TOKEN"])
+        if not projectKey:
+            return self._blocked("jira", action, connector, "missingJiraProjectKey", missingEnv=["JIRA_PROJECT_KEY"])
+        endpoint = f"{baseUrl}/rest/api/3/issue"
+        summary = str(payload.get("summary", payload.get("title", payload.get("subject", "Picux case"))) or "Picux case")
+        description = self._message(payload, fallback=str(payload.get("description", "") or ""))
+        issueType = str(payload.get("issueType", payload.get("jiraIssueType", "Task")) or "Task")
+        body = {
+            "fields": {
+                "project": {"key": projectKey},
+                "summary": summary[:255],
+                "issuetype": {"name": issueType},
+                "description": self._jiraDoc(description),
+            }
+        }
+        status, responseBody, errText = self._postJson(endpoint, body, headers={"Authorization": authHeader})
+        ok = 200 <= status < 300
+        key = str(responseBody.get("key", responseBody.get("id", "")) or "")
+        result = {
+            "ok": ok,
+            "status": "created" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": key or self._stableId("jiraIssue", {"actionId": action.get("actionId", ""), "summary": summary}),
+            "channel": "ticketing",
+            "credentialRefs": [authRef, projectKeyRef],
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        source = f"{baseUrl}/browse/{key}" if key else endpoint
+        return self._adapterResult("jira", action, connector, result, endpoint=source)
+
+    def _salesforce(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._bearerToken(connector, session, ("SALESFORCE_ACCESS_TOKEN", "PICUX_SALESFORCE_ACCESS_TOKEN"))
+        instanceUrl = self._providerUrl(connector, session, payload, "salesforceInstanceUrl", "").rstrip("/") or self._env(("SALESFORCE_INSTANCE_URL", "PICUX_SALESFORCE_INSTANCE_URL"))[0].rstrip("/")
+        if not token:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("salesforce", action, connector, "missingBridgeCredentials", missingEnv=["SALESFORCE_ACCESS_TOKEN"])
+        if not instanceUrl:
+            return self._blocked("salesforce", action, connector, "missingSalesforceInstanceUrl", missingEnv=["SALESFORCE_INSTANCE_URL"])
+        version = str(payload.get("salesforceApiVersion", "60.0") or "60.0")
+        endpoint = f"{instanceUrl}/services/data/v{version}/sobjects/Case"
+        subject = str(payload.get("subject", payload.get("title", "Picux case")) or "Picux case")
+        description = self._message(payload, fallback=str(payload.get("description", "") or ""))
+        body = {
+            "Subject": subject[:255],
+            "Description": description[:32000],
+            "Origin": str(payload.get("origin", "Picux") or "Picux"),
+            "Status": str(payload.get("caseStatus", payload.get("status", "New")) or "New"),
+        }
+        email = self._email(payload)
+        if email:
+            body["SuppliedEmail"] = email
+        status, responseBody, errText = self._postJson(endpoint, body, headers={"Authorization": f"Bearer {token}"})
+        ok = 200 <= status < 300 and responseBody.get("success", True) is not False
+        caseId = str(responseBody.get("id", responseBody.get("caseId", "")) or "")
+        result = {
+            "ok": ok,
+            "status": "created" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": caseId or self._stableId("salesforceCase", {"actionId": action.get("actionId", ""), "subject": subject}),
+            "channel": "crm",
+            "credentialRefs": [tokenKey],
+            "response": responseBody,
+            "reason": "" if ok else errText or str(responseBody.get("errors", f"httpStatus:{status}") or ""),
+        }
+        return self._adapterResult("salesforce", action, connector, result, endpoint=f"{instanceUrl}/lightning/r/Case/{caseId}/view" if caseId else endpoint)
+
+    def _hubspot(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._bearerToken(connector, session, ("HUBSPOT_ACCESS_TOKEN", "PICUX_HUBSPOT_ACCESS_TOKEN"))
+        baseUrl = self._providerUrl(connector, session, payload, "hubspotBaseUrl", "").rstrip("/") or self._env(("HUBSPOT_BASE_URL", "PICUX_HUBSPOT_BASE_URL"))[0].rstrip("/") or "https://api.hubapi.com"
+        if not token:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("hubspot", action, connector, "missingBridgeCredentials", missingEnv=["HUBSPOT_ACCESS_TOKEN"])
+        endpoint = f"{baseUrl}/crm/v3/objects/tickets"
+        subject = str(payload.get("subject", payload.get("title", "Picux case")) or "Picux case")
+        body = self._message(payload, fallback=str(payload.get("description", "") or "Picux case created by Bridge."))
+        requestBody = {
+            "properties": {
+                "subject": subject[:255],
+                "content": body[:64000],
+                "source_type": str(payload.get("sourceType", "PICUX") or "PICUX"),
+            }
+        }
+        email = self._email(payload)
+        if email:
+            requestBody["properties"]["source_ref"] = email
+        status, responseBody, errText = self._postJson(endpoint, requestBody, headers={"Authorization": f"Bearer {token}"})
+        ok = 200 <= status < 300
+        ticketId = str(responseBody.get("id", responseBody.get("ticketId", "")) or "")
+        result = {
+            "ok": ok,
+            "status": "created" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": ticketId or self._stableId("hubspotTicket", {"actionId": action.get("actionId", ""), "subject": subject}),
+            "channel": "crm",
+            "credentialRefs": [tokenKey],
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        return self._adapterResult("hubspot", action, connector, result, endpoint=f"{baseUrl}/contacts/{ticketId}" if ticketId else endpoint)
+
+    def _zendesk(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._bearerToken(connector, session, ("ZENDESK_ACCESS_TOKEN", "PICUX_ZENDESK_ACCESS_TOKEN", "ZENDESK_API_TOKEN"))
+        baseUrl = self._providerUrl(connector, session, payload, "zendeskBaseUrl", "").rstrip("/") or self._env(("ZENDESK_BASE_URL", "PICUX_ZENDESK_BASE_URL"))[0].rstrip("/")
+        if not token:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("zendesk", action, connector, "missingBridgeCredentials", missingEnv=["ZENDESK_ACCESS_TOKEN"])
+        if not baseUrl:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("zendesk", action, connector, "missingZendeskBaseUrl", missingEnv=["ZENDESK_BASE_URL"])
+        endpoint = f"{baseUrl}/api/v2/tickets.json"
+        subject = str(payload.get("subject", payload.get("title", "Picux case")) or "Picux case")
+        body = self._message(payload, fallback=str(payload.get("description", "") or "Picux case created by Bridge."))
+        requestBody: dict[str, Any] = {
+            "ticket": {
+                "subject": subject[:255],
+                "comment": {"body": body[:64000]},
+                "tags": ["picux"],
+            }
+        }
+        email = self._email(payload)
+        if email:
+            requestBody["ticket"]["requester"] = {"email": email}
+        headers = {"Authorization": self._zendeskAuth(token, tokenKey, connector, session)}
+        status, responseBody, errText = self._postJson(endpoint, requestBody, headers=headers)
+        ticket = responseBody.get("ticket", {}) if isinstance(responseBody.get("ticket"), dict) else responseBody
+        ok = 200 <= status < 300
+        ticketId = str(ticket.get("id", ticket.get("ticketId", "")) or "")
+        result = {
+            "ok": ok,
+            "status": "created" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": ticketId or self._stableId("zendeskTicket", {"actionId": action.get("actionId", ""), "subject": subject}),
+            "channel": "support",
+            "credentialRefs": [tokenKey],
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        return self._adapterResult("zendesk", action, connector, result, endpoint=f"{baseUrl}/agent/tickets/{ticketId}" if ticketId else endpoint)
+
+    def _sap(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._bearerToken(connector, session, ("SAP_ACCESS_TOKEN", "PICUX_SAP_ACCESS_TOKEN"))
+        baseUrl = self._providerUrl(connector, session, payload, "sapBaseUrl", "").rstrip("/") or self._env(("SAP_BASE_URL", "PICUX_SAP_BASE_URL"))[0].rstrip("/")
+        if not token:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("sap", action, connector, "missingBridgeCredentials", missingEnv=["SAP_ACCESS_TOKEN"])
+        if not baseUrl:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("sap", action, connector, "missingSapBaseUrl", missingEnv=["SAP_BASE_URL"])
+        path = str(payload.get("sapPath", payload.get("path", "/picux/bridge/actions")) or "/picux/bridge/actions")
+        if not path.startswith("/"):
+            path = f"/{path}"
+        endpoint = f"{baseUrl}{path}"
+        requestBody = {
+            "action": self._actionRef(action),
+            "connector": self._connectorRef(connector),
+            "case": {
+                "caseId": str(payload.get("caseId", action.get("caseId", "")) or ""),
+                "conversationId": str(payload.get("conversationId", action.get("conversationId", "")) or ""),
+                "subject": str(payload.get("subject", payload.get("title", "")) or ""),
+                "message": self._message(payload, fallback=str(payload.get("description", "") or "")),
+            },
+            "payload": payload,
+            "createdAt": self._now(),
+        }
+        status, responseBody, errText = self._postJson(endpoint, requestBody, headers={"Authorization": f"Bearer {token}"})
+        ok = 200 <= status < 300
+        result = {
+            "ok": ok,
+            "status": "synced" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": str(responseBody.get("id", responseBody.get("documentId", responseBody.get("providerRef", ""))) or self._stableId("sapSync", {"actionId": action.get("actionId", ""), "status": status})),
+            "channel": "erp",
+            "credentialRefs": [tokenKey],
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        return self._adapterResult("sap", action, connector, result, endpoint=endpoint)
+
+    def _twilioVoice(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        sid, sidKey = self._fieldValue(
+            connector,
+            session,
+            payload,
+            ("twilioAccountSid", "accountSid", "sid", "PICUX_TWILIO_ACCOUNT_SID", "TWILIO_ACCOUNT_SID"),
+            ("PICUX_TWILIO_ACCOUNT_SID", "TWILIO_ACCOUNT_SID"),
+        )
+        token, tokenKey = self._secretValue(
+            connector,
+            session,
+            ("twilioAuthToken", "authToken", "PICUX_TWILIO_AUTH_TOKEN", "TWILIO_AUTH_TOKEN"),
+            ("PICUX_TWILIO_AUTH_TOKEN", "TWILIO_AUTH_TOKEN"),
+        )
+        fromNumber, fromKey = self._fieldValue(
+            connector,
+            session,
+            payload,
+            (
+                "twilioFromNumber",
+                "fromNumber",
+                "from",
+                "PICUX_TWILIO_VOICE_FROM",
+                "TWILIO_PHONE_NUMBER",
+                "PICUX_TWILIO_VERIFIED_CALLER_ID",
+            ),
+            ("PICUX_TWILIO_VOICE_FROM", "TWILIO_PHONE_NUMBER", "PICUX_TWILIO_VERIFIED_CALLER_ID"),
+        )
+        missing = [name for value, name in ((sid, "PICUX_TWILIO_ACCOUNT_SID"), (token, "PICUX_TWILIO_AUTH_TOKEN"), (fromNumber, "PICUX_TWILIO_VOICE_FROM")) if not value]
+        phone = self._phone(payload)
+        if not phone:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("twilioVoice", action, connector, "missingDestinationPhone", missingEnv=[])
+        if missing:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("twilioVoice", action, connector, "missingBridgeCredentials", missingEnv=missing)
+        baseUrl = self._providerUrl(connector, session, payload, "twilioBaseUrl", "https://api.twilio.com").rstrip("/")
+        endpoint = f"{baseUrl}/2010-04-01/Accounts/{parse.quote(sid)}/Calls.json"
+        twiml = f"<Response><Say>{escape(self._message(payload, fallback='Picux Proxy is calling to confirm availability.'))}</Say></Response>"
+        form = {"To": phone, "From": fromNumber, "Twiml": twiml}
+        auth = base64.b64encode(f"{sid}:{token}".encode("utf-8")).decode("ascii")
+        status, responseBody, errText = self._postForm(endpoint, form, headers={"Authorization": f"Basic {auth}"})
+        ok = 200 <= status < 300
+        result = {
+            "ok": ok,
+            "status": "sent" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": str(responseBody.get("sid", responseBody.get("Sid", responseBody.get("providerRef", ""))) or self._stableId("twilioCall", {"phone": phone, "actionId": action.get("actionId", "")})),
+            "channel": "voice",
+            "toRef": self._redactPhone(phone),
+            "credentialRefs": [sidKey, tokenKey, fromKey],
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        return self._adapterResult("twilioVoice", action, connector, result, endpoint=endpoint)
+
+    def _whatsapp(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._secretValue(
+            connector,
+            session,
+            ("whatsappAccessToken", "accessToken", "WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_TOKEN"),
+            ("WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_TOKEN"),
+        )
+        phoneNumberId, phoneKey = self._fieldValue(
+            connector,
+            session,
+            payload,
+            ("whatsappPhoneNumberId", "phoneNumberId", "WHATSAPP_PHONE_NUMBER_ID", "META_WHATSAPP_PHONE_NUMBER_ID"),
+            ("WHATSAPP_PHONE_NUMBER_ID", "META_WHATSAPP_PHONE_NUMBER_ID"),
+        )
+        toPhone = self._phone(payload)
+        missing = [name for value, name in ((token, "WHATSAPP_ACCESS_TOKEN"), (phoneNumberId, "WHATSAPP_PHONE_NUMBER_ID")) if not value]
+        if not toPhone:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("whatsapp", action, connector, "missingDestinationPhone", missingEnv=[])
+        if missing:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("whatsapp", action, connector, "missingBridgeCredentials", missingEnv=missing)
+        baseUrl = self._providerUrl(connector, session, payload, "whatsappBaseUrl", "https://graph.facebook.com/v19.0").rstrip("/")
+        endpoint = f"{baseUrl}/{parse.quote(phoneNumberId)}/messages"
+        body = {
+            "messaging_product": "whatsapp",
+            "to": toPhone.lstrip("+"),
+            "type": "text",
+            "text": {"body": self._message(payload, fallback="Picux Proxy needs your confirmation.")},
+        }
+        status, responseBody, errText = self._postJson(endpoint, body, headers={"Authorization": f"Bearer {token}"})
+        messages = responseBody.get("messages", []) if isinstance(responseBody.get("messages"), list) else []
+        first = messages[0] if messages and isinstance(messages[0], dict) else {}
+        ok = 200 <= status < 300
+        result = {
+            "ok": ok,
+            "status": "sent" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": str(first.get("id", responseBody.get("messageId", "")) or self._stableId("whatsappMsg", {"phone": toPhone, "actionId": action.get("actionId", "")})),
+            "channel": "whatsapp",
+            "toRef": self._redactPhone(toPhone),
+            "credentialRefs": [tokenKey, phoneKey],
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        return self._adapterResult("whatsapp", action, connector, result, endpoint=endpoint)
+
+    def _slack(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        token, tokenKey = self._bearerToken(connector, session, ("SLACK_BOT_TOKEN", "PICUX_SLACK_BOT_TOKEN"))
+        channel = str(payload.get("channelId", payload.get("channel", payload.get("to", ""))) or "")
+        if token:
+            if not channel:
+                if not self._hostedRequired(connector, session, payload):
+                    return {}
+                return self._blocked("slack", action, connector, "missingSlackChannel", missingEnv=[])
+            baseUrl = self._providerUrl(connector, session, payload, "slackApiBaseUrl", "https://slack.com/api").rstrip("/")
+            endpoint = f"{baseUrl}/chat.postMessage"
+            status, responseBody, errText = self._postJson(
+                endpoint,
+                {"channel": channel, "text": self._message(payload, fallback="Picux Bridge notification.")},
+                headers={"Authorization": f"Bearer {token}"},
+            )
+            ok = 200 <= status < 300 and responseBody.get("ok", True) is not False
+            result = {
+                "ok": ok,
+                "status": "sent" if ok else "ioError",
+                "providerStatus": status,
+                "providerRef": str(responseBody.get("ts", responseBody.get("messageId", "")) or self._stableId("slackMsg", {"actionId": action.get("actionId", ""), "channel": channel})),
+                "channel": "slack",
+                "credentialRefs": [tokenKey],
+                "response": responseBody,
+                "reason": "" if ok else str(responseBody.get("error", errText or f"httpStatus:{status}") or ""),
+            }
+            return self._adapterResult("slack", action, connector, result, endpoint=endpoint)
+
+        endpoint = str(connector.get("endpoint", "") or "")
+        if not endpoint.startswith(("http://", "https://")):
+            endpoint = self._env(("SLACK_WEBHOOK_URL", "PICUX_SLACK_WEBHOOK_URL"))[0]
+        if not endpoint:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("slack", action, connector, "missingBridgeCredentials", missingEnv=["SLACK_WEBHOOK_URL", "SLACK_BOT_TOKEN"])
+        status, responseBody, errText = self._postJson(endpoint, {"text": self._message(payload, fallback="Picux Bridge notification.")})
+        ok = 200 <= status < 300
+        result = {
+            "ok": ok,
+            "status": "sent" if ok else "ioError",
+            "providerStatus": status,
+            "providerRef": self._stableId("slackMsg", {"actionId": action.get("actionId", ""), "status": status}),
+            "channel": "slack",
+            "response": responseBody,
+            "reason": "" if ok else errText or f"httpStatus:{status}",
+        }
+        return self._adapterResult("slack", action, connector, result, endpoint=endpoint)
+
+    def _smtp(self, action: dict[str, Any], connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any]) -> dict[str, Any]:
+        host, hostKey = self._env(("PICUX_SMTP_HOST", "SMTP_HOST"))
+        portRaw, portKey = self._env(("PICUX_SMTP_PORT", "SMTP_PORT"))
+        user, userKey = self._env(("PICUX_SMTP_USER", "SMTP_USER"))
+        password, passwordKey = self._env(("PICUX_SMTP_PASSWORD", "SMTP_PASSWORD"))
+        fromEmail, fromKey = self._env(("PICUX_SMTP_FROM", "SMTP_FROM", "PICUX_BRIDGE_FROM_EMAIL"))
+        toEmail = self._email(payload)
+        missing = [name for value, name in ((host, "PICUX_SMTP_HOST"), (fromEmail, "PICUX_SMTP_FROM")) if not value]
+        if not toEmail:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("smtp", action, connector, "missingDestinationEmail", missingEnv=[])
+        if missing:
+            if not self._hostedRequired(connector, session, payload):
+                return {}
+            return self._blocked("smtp", action, connector, "missingBridgeCredentials", missingEnv=missing)
+        msg = EmailMessage()
+        msg["From"] = fromEmail
+        msg["To"] = toEmail
+        msg["Subject"] = str(payload.get("subject", payload.get("title", "Picux Resolve message")) or "Picux Resolve message")
+        msg.set_content(self._message(payload, fallback=str(payload.get("body", "") or "Picux Resolve message.")))
+        try:
+            port = int(portRaw or 587)
+            with smtplib.SMTP(host, port, timeout=self.timeoutSeconds) as smtp:
+                if str(self._env(("PICUX_SMTP_TLS", "SMTP_TLS"))[0] or "true").lower() not in {"0", "false", "no"}:
+                    smtp.starttls(context=ssl.create_default_context())
+                if user and password:
+                    smtp.login(user, password)
+                smtp.send_message(msg)
+            result = {
+                "ok": True,
+                "status": "sent",
+                "providerStatus": 250,
+                "providerRef": self._stableId("smtpMsg", {"actionId": action.get("actionId", ""), "to": toEmail, "subject": msg["Subject"]}),
+                "channel": "email",
+                "toRef": self._redactEmail(toEmail),
+                "credentialRefs": [hostKey, portKey, userKey, passwordKey, fromKey],
+                "response": {"accepted": [self._redactEmail(toEmail)]},
+            }
+        except Exception as exc:
+            result = {
+                "ok": False,
+                "status": "ioError",
+                "providerStatus": 0,
+                "providerRef": "",
+                "channel": "email",
+                "toRef": self._redactEmail(toEmail),
+                "credentialRefs": [hostKey, portKey, userKey, passwordKey, fromKey],
+                "reason": str(exc),
+            }
+        return self._adapterResult("smtp", action, connector, result, endpoint=f"smtp://{host}:{portRaw or 587}")
+
+    def _adapterResult(self, kind: str, action: dict[str, Any], connector: dict[str, Any], result: dict[str, Any], *, endpoint: str = "") -> dict[str, Any]:
+        proof = self._proof(kind, action, connector, result, endpoint=endpoint)
+        return {
+            "adapter": {
+                "kind": kind,
+                "mode": "picuxHostedAdapter",
+                "provider": str(connector.get("meta", {}).get("provider", connector.get("provider", connector.get("connectorId", ""))) if isinstance(connector.get("meta", {}), dict) else connector.get("connectorId", "")),
+            },
+            "result": result,
+            "proof": proof,
+        }
+
+    def _blocked(self, kind: str, action: dict[str, Any], connector: dict[str, Any], reason: str, *, missingEnv: list[str]) -> dict[str, Any]:
+        result = {
+            "ok": False,
+            "status": "blocked",
+            "reason": reason,
+            "missingEnv": missingEnv,
+            "providerRef": "",
+        }
+        return self._adapterResult(kind, action, connector, result)
+
+    def _postJson(self, url: str, body: dict[str, Any], *, headers: dict[str, str] | None = None) -> tuple[int, dict[str, Any], str]:
+        data = json.dumps(body, ensure_ascii=True, sort_keys=True).encode("utf-8")
+        req = request.Request(
+            url,
+            data=data,
+            method="POST",
+            headers={"Accept": "application/json", "Content-Type": "application/json", **(headers or {})},
+        )
+        return self._open(req)
+
+    def _postForm(self, url: str, form: dict[str, Any], *, headers: dict[str, str] | None = None) -> tuple[int, dict[str, Any], str]:
+        data = parse.urlencode({key: str(value) for key, value in form.items()}).encode("utf-8")
+        req = request.Request(
+            url,
+            data=data,
+            method="POST",
+            headers={"Accept": "application/json", "Content-Type": "application/x-www-form-urlencoded", **(headers or {})},
+        )
+        return self._open(req)
+
+    def _open(self, req: request.Request) -> tuple[int, dict[str, Any], str]:
+        try:
+            with request.urlopen(req, timeout=self.timeoutSeconds) as response:
+                raw = response.read()
+                return int(response.status), self._body(raw), ""
+        except error.HTTPError as exc:
+            raw = exc.read()
+            return int(exc.code), self._body(raw), raw.decode("utf-8", errors="replace")[:1000]
+        except Exception as exc:
+            return 0, {}, str(exc)
+
+    @staticmethod
+    def _body(raw: bytes) -> dict[str, Any]:
+        text = raw.decode("utf-8", errors="replace")
+        try:
+            decoded = json.loads(text or "{}")
+        except Exception:
+            return {"text": text[:1000]} if text else {}
+        body = decoded if isinstance(decoded, dict) else {"data": decoded}
+        return HostedBridgeAdapters._safeProviderBody(body)
+
+    def _env(self, names: tuple[str, ...]) -> tuple[str, str]:
+        for name in names:
+            resolved = self.secrets.resolve(f"env:{name}")
+            if resolved.available:
+                return resolved.value, name
+        return "", ""
+
+    def _credentialToken(self, connector: dict[str, Any], session: dict[str, Any]) -> str:
+        credential = connector.get("credential", {}) if isinstance(connector.get("credential"), dict) else {}
+        resolved = self.secrets.resolve(
+            str(credential.get("tokenRef", credential.get("secretRef", "")) or ""),
+            envName=str(credential.get("env", "") or ""),
+            source="connector.credential",
+        )
+        if resolved.available:
+            return resolved.value
+        value, _source = self._credentialValue(
+            connector,
+            session,
+            ("token", "accessToken", "apiKey", "bearer", "authorization", "authToken"),
+            allowSingleFallback=True,
+        )
+        if value:
+            return value
+        return ""
+
+    def _bearerToken(self, connector: dict[str, Any], session: dict[str, Any], envNames: tuple[str, ...]) -> tuple[str, str]:
+        aliases = (*envNames, "token", "accessToken", "apiKey", "bearer", "authorization")
+        return self._secretValue(connector, session, aliases, envNames, allowSingleFallback=True)
+
+    def _secretValue(
+        self,
+        connector: dict[str, Any],
+        session: dict[str, Any],
+        aliases: tuple[str, ...],
+        envNames: tuple[str, ...],
+        *,
+        allowSingleFallback: bool = False,
+    ) -> tuple[str, str]:
+        value, source = self._credentialValue(connector, session, aliases, allowSingleFallback=allowSingleFallback)
+        if value:
+            return value, source
+        return self._env(envNames)
+
+    def _fieldValue(
+        self,
+        connector: dict[str, Any],
+        session: dict[str, Any],
+        payload: dict[str, Any],
+        aliases: tuple[str, ...],
+        envNames: tuple[str, ...] = (),
+        *,
+        fallback: str = "",
+    ) -> tuple[str, str]:
+        for source, record in (
+            ("payload", payload),
+            ("session.providerMeta", session.get("providerMeta", {}) if isinstance(session.get("providerMeta"), dict) else {}),
+            ("connector.meta", connector.get("meta", {}) if isinstance(connector.get("meta"), dict) else {}),
+        ):
+            if not isinstance(record, dict):
+                continue
+            for key in aliases:
+                if key in record and str(record.get(key, "") or "").strip():
+                    value = str(record.get(key, "") or "").strip()
+                    resolved = self._maybeResolve(value, f"{source}.{key}")
+                    if resolved[0]:
+                        return resolved
+                    return value, f"{source}.{key}"
+        value, source = self._credentialValue(connector, session, aliases)
+        if value:
+            return value, source
+        if envNames:
+            return self._env(envNames)
+        return fallback, ""
+
+    def _credentialValue(
+        self,
+        connector: dict[str, Any],
+        session: dict[str, Any],
+        aliases: tuple[str, ...],
+        *,
+        allowSingleFallback: bool = False,
+    ) -> tuple[str, str]:
+        wanted = {self._tokenKey(item) for item in aliases if str(item or "").strip()}
+        refs = self._credentialRefs(connector, session)
+        matches = []
+        for item in refs:
+            keys = {
+                self._tokenKey(item.get("resource", "")),
+                self._tokenKey(item.get("kind", "")),
+                self._tokenKey(item.get("ref", "")),
+                self._tokenKey(str(item.get("ref", "")).split(":", 1)[-1]),
+            }
+            if wanted and not (wanted & keys):
+                continue
+            matches.append(item)
+        if not matches and allowSingleFallback and len(refs) == 1:
+            matches = refs
+        for item in matches:
+            ref = str(item.get("ref", "") or "")
+            resolved = self.secrets.resolve(ref, source=f"session.credentialRefs.{item.get('resource', item.get('kind', 'credential'))}")
+            if resolved.available:
+                return resolved.value, ref
+        return "", ""
+
+    @staticmethod
+    def _credentialRefs(connector: dict[str, Any], session: dict[str, Any]) -> list[dict[str, Any]]:
+        refs: list[dict[str, Any]] = []
+        for item in session.get("credentialRefs", []) if isinstance(session.get("credentialRefs"), list) else []:
+            if isinstance(item, dict) and str(item.get("ref", item.get("tokenRef", item.get("secretRef", item.get("env", "")))) or "").strip():
+                if HostedBridgeAdapters._expired(str(item.get("expiresAt", "") or "")):
+                    continue
+                refs.append(
+                    {
+                        "ref": str(item.get("ref", item.get("tokenRef", item.get("secretRef", item.get("env", "")))) or ""),
+                        "kind": str(item.get("kind", item.get("type", "")) or ""),
+                        "resource": str(item.get("resource", "") or ""),
+                        "expiresAt": str(item.get("expiresAt", "") or ""),
+                    }
+                )
+        meta = connector.get("meta", {}) if isinstance(connector.get("meta"), dict) else {}
+        for item in meta.get("credentialRefs", []) if isinstance(meta.get("credentialRefs"), list) else []:
+            if isinstance(item, dict) and str(item.get("ref", item.get("tokenRef", item.get("secretRef", item.get("env", "")))) or "").strip():
+                if HostedBridgeAdapters._expired(str(item.get("expiresAt", "") or "")):
+                    continue
+                refs.append(
+                    {
+                        "ref": str(item.get("ref", item.get("tokenRef", item.get("secretRef", item.get("env", "")))) or ""),
+                        "kind": str(item.get("kind", item.get("type", "")) or ""),
+                        "resource": str(item.get("resource", "") or ""),
+                        "expiresAt": str(item.get("expiresAt", "") or ""),
+                    }
+                )
+        return refs
+
+    @staticmethod
+    def _expired(value: str) -> bool:
+        raw = str(value or "").strip()
+        if not raw:
+            return False
+        if raw.endswith("Z"):
+            raw = raw[:-1] + "+00:00"
+        try:
+            parsed = datetime.fromisoformat(raw)
+        except Exception:
+            return True
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.astimezone(timezone.utc) <= datetime.now(timezone.utc)
+
+    @staticmethod
+    def _safeProviderBody(value: Any) -> Any:
+        secretKeys = {
+            "authorization",
+            "bearer",
+            "cookie",
+            "set-cookie",
+            "setcookie",
+            "token",
+            "apikey",
+            "api_key",
+            "secret",
+            "password",
+            "privatekey",
+            "private_key",
+            "clientsecret",
+            "client_secret",
+            "accesstoken",
+            "access_token",
+            "refreshtoken",
+            "refresh_token",
+            "paymenttoken",
+            "payment_token",
+        }
+        if isinstance(value, list):
+            return [HostedBridgeAdapters._safeProviderBody(item) for item in value]
+        if not isinstance(value, dict):
+            return value
+        out: dict[str, Any] = {}
+        for key, item in value.items():
+            normalized = "".join(ch for ch in str(key).lower() if ch.isalnum() or ch in {"_", "-"})
+            compact = "".join(ch for ch in str(key).lower() if ch.isalnum())
+            if normalized in secretKeys or compact in secretKeys:
+                out[key] = "[redacted]"
+            else:
+                out[key] = HostedBridgeAdapters._safeProviderBody(item)
+        return out
+
+    def _maybeResolve(self, value: str, source: str) -> tuple[str, str]:
+        if value.startswith(("env:", "vault:")) or (value.isupper() and "_" in value):
+            resolved = self.secrets.resolve(value, source=source)
+            if resolved.available:
+                return resolved.value, value
+        return "", ""
+
+    @staticmethod
+    def _tokenKey(value: Any) -> str:
+        return "".join(ch for ch in str(value or "").lower() if ch.isalnum())
+
+    def _jiraAuth(self, connector: dict[str, Any], session: dict[str, Any]) -> tuple[str, str]:
+        token, tokenRef = self._bearerToken(connector, session, ("JIRA_ACCESS_TOKEN", "ATLASSIAN_ACCESS_TOKEN", "JIRA_API_TOKEN", "ATLASSIAN_API_TOKEN"))
+        if not token:
+            return "", ""
+        email, emailRef = self._fieldValue(connector, session, {}, ("jiraEmail", "atlassianEmail", "JIRA_EMAIL", "ATLASSIAN_EMAIL"), ("JIRA_EMAIL", "ATLASSIAN_EMAIL"))
+        if email:
+            basic = base64.b64encode(f"{email}:{token}".encode("utf-8")).decode("ascii")
+            return f"Basic {basic}", f"{emailRef}+{tokenRef}"
+        return f"Bearer {token}", tokenRef
+
+    def _zendeskAuth(self, token: str, tokenRef: str, connector: dict[str, Any], session: dict[str, Any]) -> str:
+        email, _emailRef = self._fieldValue(connector, session, {}, ("zendeskEmail", "ZENDESK_EMAIL", "PICUX_ZENDESK_EMAIL"), ("ZENDESK_EMAIL", "PICUX_ZENDESK_EMAIL"))
+        if email:
+            basic = base64.b64encode(f"{email}/token:{token}".encode("utf-8")).decode("ascii")
+            return f"Basic {basic}"
+        return f"Bearer {token}"
+
+    @staticmethod
+    def _jiraDoc(text: str) -> dict[str, Any]:
+        return {
+            "type": "doc",
+            "version": 1,
+            "content": [
+                {
+                    "type": "paragraph",
+                    "content": [{"type": "text", "text": str(text or "Picux case created by Bridge.")[:32000]}],
+                }
+            ],
+        }
+
+    @staticmethod
+    def _providerUrl(connector: dict[str, Any], session: dict[str, Any], payload: dict[str, Any], key: str, fallback: str) -> str:
+        meta = connector.get("meta", {}) if isinstance(connector.get("meta"), dict) else {}
+        providerMeta = session.get("providerMeta", {}) if isinstance(session.get("providerMeta"), dict) else {}
+        return str(providerMeta.get(key, meta.get(key, fallback)) or fallback)
+
+    @staticmethod
+    def _message(payload: dict[str, Any], *, fallback: str) -> str:
+        voiceCall = payload.get("voiceCall", {}) if isinstance(payload.get("voiceCall"), dict) else {}
+        candidates = (
+            payload.get("text"),
+            payload.get("message"),
+            payload.get("body"),
+            payload.get("script"),
+            voiceCall.get("prompt"),
+            voiceCall.get("script"),
+            fallback,
+        )
+        return str(next((item for item in candidates if str(item or "").strip()), fallback) or fallback)
+
+    @staticmethod
+    def _phone(payload: dict[str, Any]) -> str:
+        voiceCall = payload.get("voiceCall", {}) if isinstance(payload.get("voiceCall"), dict) else {}
+        candidates = (
+            payload.get("to"),
+            payload.get("phone"),
+            payload.get("number"),
+            payload.get("phoneNumber"),
+            voiceCall.get("to"),
+            voiceCall.get("phone"),
+            voiceCall.get("number"),
+        )
+        return str(next((item for item in candidates if str(item or "").strip()), "") or "")
+
+    @staticmethod
+    def _email(payload: dict[str, Any]) -> str:
+        value = payload.get("to", payload.get("email", ""))
+        if isinstance(value, list):
+            value = next((item for item in value if str(item or "").strip()), "")
+        return str(value or "")
+
+    @staticmethod
+    def _gmailRaw(payload: dict[str, Any], toEmail: str) -> str:
+        msg = EmailMessage()
+        fromEmail = str(payload.get("from", payload.get("sender", "")) or "")
+        if fromEmail:
+            msg["From"] = fromEmail
+        msg["To"] = toEmail
+        cc = payload.get("cc", [])
+        if isinstance(cc, list):
+            cc = ", ".join(str(item) for item in cc if str(item))
+        if str(cc or "").strip():
+            msg["Cc"] = str(cc)
+        msg["Subject"] = str(payload.get("subject", payload.get("title", "Picux Resolve message")) or "Picux Resolve message")
+        msg.set_content(str(payload.get("body", payload.get("text", payload.get("message", ""))) or ""))
+        return base64.urlsafe_b64encode(bytes(msg)).decode("ascii").rstrip("=")
+
+    @staticmethod
+    def _redactPhone(value: str) -> str:
+        clean = str(value or "")
+        return f"{clean[:3]}***{clean[-3:]}" if len(clean) > 7 else "***"
+
+    @staticmethod
+    def _redactEmail(value: str) -> str:
+        text = str(value or "")
+        if "@" not in text:
+            return "***"
+        left, right = text.split("@", 1)
+        return f"{left[:2]}***@{right}"
+
+    @staticmethod
+    def _actionRef(action: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "actionId": str(action.get("actionId", "") or ""),
+            "action": str(action.get("action", "") or ""),
+            "resource": str(action.get("resource", "") or ""),
+            "caseId": str(action.get("caseId", "") or ""),
+            "conversationId": str(action.get("conversationId", "") or ""),
+        }
+
+    @staticmethod
+    def _connectorRef(connector: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "connectorId": str(connector.get("connectorId", "") or ""),
+            "kind": str(connector.get("kind", "") or ""),
+            "endpoint": str(connector.get("endpoint", "") or ""),
+            "caps": connector.get("caps", []) if isinstance(connector.get("caps"), list) else [],
+        }
+
+    @staticmethod
+    def _sessionRef(session: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "sessionId": str(session.get("sessionId", "") or ""),
+            "connectorId": str(session.get("connectorId", "") or ""),
+            "executionMode": str(session.get("executionMode", "") or ""),
+            "subjectId": str(session.get("subjectId", "") or ""),
+        }
+
+    def _proof(self, kind: str, action: dict[str, Any], connector: dict[str, Any], result: dict[str, Any], *, endpoint: str = "") -> dict[str, Any]:
+        proofPayload = {
+            "kind": kind,
+            "actionId": action.get("actionId", ""),
+            "connectorId": connector.get("connectorId", ""),
+            "providerRef": result.get("providerRef", ""),
+            "status": result.get("status", ""),
+            "providerStatus": result.get("providerStatus", ""),
+        }
+        artifactRef = self._stableId("bridgeProof", proofPayload)
+        return {
+            "proofId": artifactRef,
+            "artifactRef": artifactRef,
+            "kind": f"{kind}Proof",
+            "status": "sourceBound" if result.get("ok") else str(result.get("status", "blocked") or "blocked"),
+            "label": f"{kind} Bridge execution proof",
+            "sourceUrl": self._safeEndpoint(endpoint),
+            "hash": hashlib.sha256(json.dumps(proofPayload, ensure_ascii=True, sort_keys=True).encode("utf-8")).hexdigest(),
+            "meta": proofPayload,
+        }
+
+    @staticmethod
+    def _safeEndpoint(endpoint: str) -> str:
+        parsed = parse.urlparse(str(endpoint or ""))
+        if not parsed.scheme:
+            return ""
+        return f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
+
+    @staticmethod
+    def _stableId(prefix: str, payload: dict[str, Any]) -> str:
+        raw = json.dumps(payload, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        return f"{prefix}_" + hashlib.sha256(raw).hexdigest()[:24]
+
+    @staticmethod
+    def _now() -> str:
+        return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")