patchr 0.1.0__py3-none-any.whl

picux/portals/__init__.py

@@ -0,0 +1,17 @@
+from picux.portals.templates import (
+    applyPortalActionTemplate,
+    getPortalActionTemplate,
+    getPortalRecoveryPlaybook,
+    instantiatePortalRecoveryPlaybook,
+    portalActionTemplates,
+    portalRecoveryPlaybooks,
+)
+
+__all__ = [
+    "applyPortalActionTemplate",
+    "getPortalActionTemplate",
+    "getPortalRecoveryPlaybook",
+    "instantiatePortalRecoveryPlaybook",
+    "portalActionTemplates",
+    "portalRecoveryPlaybooks",
+]

picux/portals/templates.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+from urllib.parse import urljoin
+
+
+PORTAL_ACTION_TEMPLATES: tuple[dict[str, Any], ...] = (
+    {
+        "templateId": "checkStatus",
+        "name": "Check Account Status",
+        "kind": "checkStatus",
+        "description": "Open an authenticated portal status page and capture the latest case, order, claim, or ticket state.",
+        "targetPath": "/status",
+        "requiredInputs": ["recordRef"],
+        "steps": [
+            {"label": "Open status page", "action": "navigate", "proofRequired": False},
+            {"label": "Search record reference", "action": "fill", "selector": "[name='recordRef']", "valueKey": "recordRef", "proofRequired": False},
+            {"label": "Capture status proof", "action": "capture", "proofRequired": True},
+        ],
+        "proofRequirements": ["domSnapshot", "confirmationOrStatus"],
+    },
+    {
+        "templateId": "retrieveRecord",
+        "name": "Retrieve Portal Record",
+        "kind": "retrieveRecord",
+        "description": "Find and capture a receipt, account record, policy document, order, or claim document from a portal.",
+        "targetPath": "/records",
+        "requiredInputs": ["recordRef"],
+        "steps": [
+            {"label": "Open records page", "action": "navigate", "proofRequired": False},
+            {"label": "Find record", "action": "fill", "selector": "[name='recordRef']", "valueKey": "recordRef", "proofRequired": False},
+            {"label": "Download or capture record", "action": "capture", "proofRequired": True},
+        ],
+        "proofRequirements": ["downloadedRecordOrDomSnapshot"],
+    },
+    {
+        "templateId": "submitClaim",
+        "name": "Submit Claim Form",
+        "kind": "submitClaim",
+        "description": "Submit a merchant, carrier, utility, or provider claim form and capture a confirmation proof.",
+        "targetPath": "/claims/new",
+        "requiredInputs": ["claimText"],
+        "steps": [
+            {"label": "Open claim form", "action": "navigate", "proofRequired": False},
+            {"label": "Enter claim details", "action": "fill", "selector": "[name='claim']", "valueKey": "claimText", "proofRequired": False},
+            {"label": "Attach evidence", "action": "upload", "selector": "input[type='file']", "valueKey": "attachmentRefs", "proofRequired": False},
+            {"label": "Submit claim", "action": "click", "selector": "[type='submit']", "proofRequired": True},
+            {"label": "Capture confirmation", "action": "capture", "proofRequired": True},
+        ],
+        "proofRequirements": ["confirmationNumber", "domSnapshot"],
+    },
+    {
+        "templateId": "uploadDocument",
+        "name": "Upload Document",
+        "kind": "uploadDocument",
+        "description": "Upload one or more evidence documents to an authenticated portal and capture upload proof.",
+        "targetPath": "/documents/upload",
+        "requiredInputs": ["attachmentRefs"],
+        "steps": [
+            {"label": "Open upload page", "action": "navigate", "proofRequired": False},
+            {"label": "Upload document", "action": "upload", "selector": "input[type='file']", "valueKey": "attachmentRefs", "proofRequired": False},
+            {"label": "Submit upload", "action": "click", "selector": "[type='submit']", "proofRequired": True},
+            {"label": "Capture upload proof", "action": "capture", "proofRequired": True},
+        ],
+        "proofRequirements": ["uploadConfirmation", "domSnapshot"],
+    },
+)
+
+PORTAL_RECOVERY_PLAYBOOKS: tuple[dict[str, Any], ...] = (
+    {
+        "playbookId": "merchantDamageClaim",
+        "name": "Merchant Damage Claim",
+        "description": "Retrieve the purchase record, submit a merchant damage claim, and check claim status.",
+        "providerTypes": ["merchant", "retailer", "marketplace"],
+        "requiredInputs": ["recordRef", "claimText"],
+        "optionalInputs": ["attachmentRefs"],
+        "actions": [
+            {"ref": "retrieveOrderRecord", "templateId": "retrieveRecord", "label": "Retrieve order or receipt record", "targetPath": "/orders", "inputMap": {"recordRef": "recordRef"}},
+            {"ref": "submitDamageClaim", "templateId": "submitClaim", "label": "Submit damage claim", "targetPath": "/claims/new", "inputMap": {"claimText": "claimText", "attachmentRefs": "attachmentRefs"}},
+            {"ref": "checkClaimStatus", "templateId": "checkStatus", "label": "Check claim status", "targetPath": "/claims/status", "inputMap": {"recordRef": "recordRef"}},
+        ],
+        "proofRequirements": ["purchaseRecord", "claimConfirmation", "statusSnapshot"],
+    },
+    {
+        "playbookId": "carrierDamageClaim",
+        "name": "Carrier Damage Claim",
+        "description": "Retrieve shipment records, submit a carrier damage claim, upload evidence, and check claim status.",
+        "providerTypes": ["carrier", "logistics", "shipping"],
+        "requiredInputs": ["trackingNumber", "claimText", "attachmentRefs"],
+        "optionalInputs": ["recordRef"],
+        "actions": [
+            {"ref": "retrieveShipmentRecord", "templateId": "retrieveRecord", "label": "Retrieve shipment record", "targetPath": "/shipments", "inputMap": {"recordRef": "trackingNumber"}},
+            {"ref": "submitCarrierClaim", "templateId": "submitClaim", "label": "Submit carrier damage claim", "targetPath": "/claims/damage/new", "inputMap": {"claimText": "claimText", "attachmentRefs": "attachmentRefs"}},
+            {"ref": "uploadDamageEvidence", "templateId": "uploadDocument", "label": "Upload damage evidence", "targetPath": "/claims/documents/upload", "inputMap": {"attachmentRefs": "attachmentRefs"}},
+            {"ref": "checkCarrierClaimStatus", "templateId": "checkStatus", "label": "Check carrier claim status", "targetPath": "/claims/status", "inputMap": {"recordRef": "trackingNumber"}},
+        ],
+        "proofRequirements": ["shipmentRecord", "claimConfirmation", "uploadConfirmation", "statusSnapshot"],
+    },
+    {
+        "playbookId": "utilityBillingDispute",
+        "name": "Utility Billing Dispute",
+        "description": "Retrieve billing records, submit a utility dispute, upload supporting documents, and check case status.",
+        "providerTypes": ["utility", "serviceProvider", "telecom"],
+        "requiredInputs": ["accountNumber", "claimText", "attachmentRefs"],
+        "optionalInputs": ["recordRef"],
+        "actions": [
+            {"ref": "retrieveBillingRecord", "templateId": "retrieveRecord", "label": "Retrieve billing record", "targetPath": "/billing/records", "inputMap": {"recordRef": "accountNumber"}},
+            {"ref": "submitBillingDispute", "templateId": "submitClaim", "label": "Submit billing dispute", "targetPath": "/billing/disputes/new", "inputMap": {"claimText": "claimText", "attachmentRefs": "attachmentRefs"}},
+            {"ref": "uploadDisputeDocuments", "templateId": "uploadDocument", "label": "Upload dispute documents", "targetPath": "/billing/documents/upload", "inputMap": {"attachmentRefs": "attachmentRefs"}},
+            {"ref": "checkDisputeStatus", "templateId": "checkStatus", "label": "Check dispute status", "targetPath": "/billing/disputes/status", "inputMap": {"recordRef": "accountNumber"}},
+        ],
+        "proofRequirements": ["billingRecord", "disputeConfirmation", "uploadConfirmation", "statusSnapshot"],
+    },
+)
+
+
+def portalActionTemplates(filters: dict[str, Any] | None = None) -> dict[str, Any]:
+    filters = filters or {}
+    kind = str(filters.get("kind", "") or "")
+    records = [_templateRecord(item) for item in PORTAL_ACTION_TEMPLATES]
+    if kind:
+        records = [item for item in records if item.get("kind") == kind]
+    return {"ok": True, "templates": records, "count": len(records)}
+
+
+def getPortalActionTemplate(templateId: str) -> dict[str, Any]:
+    requested = str(templateId or "")
+    for template in PORTAL_ACTION_TEMPLATES:
+        if template["templateId"] == requested:
+            return {"ok": True, "template": _templateRecord(template)}
+    return {"ok": False, "error": "portalTemplateNotFound", "templateId": requested}
+
+
+def portalRecoveryPlaybooks(filters: dict[str, Any] | None = None) -> dict[str, Any]:
+    filters = filters or {}
+    providerType = str(filters.get("providerType", filters.get("provider", "")) or "")
+    records = [_playbookRecord(item) for item in PORTAL_RECOVERY_PLAYBOOKS]
+    if providerType:
+        records = [item for item in records if providerType in item.get("providerTypes", [])]
+    return {"ok": True, "playbooks": records, "count": len(records)}
+
+
+def getPortalRecoveryPlaybook(playbookId: str) -> dict[str, Any]:
+    requested = str(playbookId or "")
+    for playbook in PORTAL_RECOVERY_PLAYBOOKS:
+        if playbook["playbookId"] == requested:
+            return {"ok": True, "playbook": _playbookRecord(playbook)}
+    return {"ok": False, "error": "portalPlaybookNotFound", "playbookId": requested}
+
+
+def instantiatePortalRecoveryPlaybook(playbookId: str, payload: dict[str, Any], *, session: dict[str, Any] | None = None) -> dict[str, Any]:
+    found = getPortalRecoveryPlaybook(playbookId)
+    if not found.get("ok"):
+        return found
+    playbook = found["playbook"]
+    session = session or {}
+    inputs = payload.get("inputs", {}) if isinstance(payload.get("inputs"), dict) else {}
+    missing = _missingPlaybookInputs(playbook, inputs)
+    if missing:
+        return {"ok": False, "status": "needsInput", "playbook": playbook, "needsInput": missing}
+    baseUrl = str(payload.get("baseUrl", session.get("baseUrl", "")) or "")
+    targetUrls = payload.get("targetUrls", {}) if isinstance(payload.get("targetUrls"), dict) else {}
+    actions = []
+    for idx, item in enumerate(playbook.get("actions", [])):
+        if not isinstance(item, dict):
+            continue
+        ref = str(item.get("ref", f"action{idx + 1}") or f"action{idx + 1}")
+        templateId = str(item.get("templateId", "") or "")
+        targetUrl = str(targetUrls.get(ref, targetUrls.get(templateId, "")) or "")
+        if not targetUrl and baseUrl:
+            targetUrl = urljoin(baseUrl.rstrip("/") + "/", str(item.get("targetPath", "") or "").lstrip("/"))
+        actionInputs = _mappedInputs(item.get("inputMap", {}), inputs)
+        actions.append(
+            {
+                "portalSessionId": str(payload.get("portalSessionId", session.get("portalSessionId", payload.get("sessionId", ""))) or ""),
+                "templateId": templateId,
+                "caseId": str(payload.get("caseId", session.get("caseId", "")) or ""),
+                "conversationId": str(payload.get("conversationId", session.get("conversationId", "")) or ""),
+                "connectorId": str(payload.get("connectorId", session.get("connectorId", "")) or ""),
+                "provider": str(payload.get("provider", session.get("provider", "")) or ""),
+                "targetUrl": targetUrl,
+                "inputs": actionInputs,
+                "meta": {
+                    "playbookId": playbookId,
+                    "playbookActionRef": ref,
+                    "playbookActionIndex": idx,
+                    "playbookActionLabel": str(item.get("label", "") or ""),
+                    "targetPath": str(item.get("targetPath", "") or ""),
+                },
+            }
+        )
+    return {"ok": True, "playbook": playbook, "actions": actions, "count": len(actions)}
+
+
+def applyPortalActionTemplate(payload: dict[str, Any], *, session: dict[str, Any] | None = None) -> dict[str, Any]:
+    templateId = str(payload.get("templateId", "") or "")
+    if not templateId:
+        return {"ok": True, "action": copy.deepcopy(payload), "template": {}}
+    found = getPortalActionTemplate(templateId)
+    if not found.get("ok"):
+        return found
+    template = found["template"]
+    session = session or {}
+    currentMeta = payload.get("meta", {}) if isinstance(payload.get("meta"), dict) else {}
+    targetUrl = str(payload.get("targetUrl", payload.get("url", "")) or "")
+    baseUrl = str(session.get("baseUrl", "") or "")
+    if not targetUrl and baseUrl:
+        targetUrl = urljoin(baseUrl.rstrip("/") + "/", str(template.get("targetPath", "") or "").lstrip("/"))
+    action = {
+        **payload,
+        "templateId": templateId,
+        "kind": str(payload.get("kind", "") or template.get("kind", "submitForm")),
+        "targetUrl": targetUrl,
+        "steps": payload.get("steps") if isinstance(payload.get("steps"), list) and payload.get("steps") else copy.deepcopy(template.get("steps", [])),
+        "meta": {
+            **currentMeta,
+            "templateId": templateId,
+            "templateName": template.get("name", ""),
+            "requiredInputs": template.get("requiredInputs", []),
+            "proofRequirements": template.get("proofRequirements", []),
+        },
+    }
+    return {"ok": True, "action": action, "template": template}
+
+
+def _templateRecord(template: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "templateId": str(template.get("templateId", "") or ""),
+        "name": str(template.get("name", "") or ""),
+        "kind": str(template.get("kind", "") or ""),
+        "description": str(template.get("description", "") or ""),
+        "targetPath": str(template.get("targetPath", "") or ""),
+        "requiredInputs": [str(item) for item in template.get("requiredInputs", []) if str(item)],
+        "steps": [copy.deepcopy(item) for item in template.get("steps", []) if isinstance(item, dict)],
+        "proofRequirements": [str(item) for item in template.get("proofRequirements", []) if str(item)],
+    }
+
+
+def _playbookRecord(playbook: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "playbookId": str(playbook.get("playbookId", "") or ""),
+        "name": str(playbook.get("name", "") or ""),
+        "description": str(playbook.get("description", "") or ""),
+        "providerTypes": [str(item) for item in playbook.get("providerTypes", []) if str(item)],
+        "requiredInputs": [str(item) for item in playbook.get("requiredInputs", []) if str(item)],
+        "optionalInputs": [str(item) for item in playbook.get("optionalInputs", []) if str(item)],
+        "actions": [copy.deepcopy(item) for item in playbook.get("actions", []) if isinstance(item, dict)],
+        "proofRequirements": [str(item) for item in playbook.get("proofRequirements", []) if str(item)],
+    }
+
+
+def _missingPlaybookInputs(playbook: dict[str, Any], inputs: dict[str, Any]) -> list[dict[str, Any]]:
+    missing = []
+    for key in playbook.get("requiredInputs", []):
+        clean = str(key or "")
+        value = inputs.get(clean)
+        if clean and (clean not in inputs or value is None or value == "" or value == []):
+            missing.append({"key": clean, "label": clean, "secret": False})
+    return missing
+
+
+def _mappedInputs(inputMap: Any, inputs: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(inputMap, dict):
+        return dict(inputs)
+    mapped = {}
+    for targetKey, sourceKey in inputMap.items():
+        target = str(targetKey or "")
+        source = str(sourceKey or "")
+        if target and source in inputs:
+            mapped[target] = inputs[source]
+    return mapped

picux/protocols/__init__.py

@@ -0,0 +1 @@
+"""Picux protocol transports and machine-readable envelopes."""

picux/protocols/a2a/__init__.py

@@ -0,0 +1,6 @@
+"""A2A protocol transport."""
+
+from .envelope import A2AEnvelope, a2aContract, createEnvelope, validateEnvelope
+from .client import AgentMeshClient
+
+__all__ = ["A2AEnvelope", "AgentMeshClient", "a2aContract", "createEnvelope", "validateEnvelope"]

picux/protocols/a2a/client.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+from urllib import request
+
+from picux.config import resolve_env
+from picux.protocols.a2a.envelope import createEnvelope
+
+
+@dataclass(frozen=True)
+class AgentMeshClient:
+    """Minimal A2A delegation client using Picux env names with legacy fallback."""
+
+    base_url: str = ""
+    token: str = ""
+    timeout_seconds: int = 20
+
+    @classmethod
+    def fromEnv(cls) -> "AgentMeshClient":
+        return cls(
+            base_url=resolve_env("PICUX_A2A_BASE_URL").value.strip().rstrip("/"),
+            token=resolve_env("PICUX_A2A_TOKEN").value.strip(),
+        )
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.base_url)
+
+    def delegate(self, *, target_agent: str, payload: dict[str, Any]) -> dict[str, Any]:
+        if not self.enabled:
+            raise RuntimeError("a2a_client_disabled")
+        envelope = createEnvelope({**payload, "toAgent": target_agent})
+        if not envelope["ok"]:
+            raise RuntimeError(f"a2a_invalid_envelope:{','.join(envelope['errors'])}")
+        headers = {"Content-Type": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        url = f"{self.base_url}/agents/{target_agent}/invoke"
+        req = request.Request(
+            url,
+            data=json.dumps({"envelope": envelope["envelope"], "payload": payload}, ensure_ascii=True).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        with request.urlopen(req, timeout=max(5, self.timeout_seconds)) as response:
+            body = json.loads(response.read().decode("utf-8"))
+        if not isinstance(body, dict):
+            raise RuntimeError("a2a_invalid_response")
+        return body

picux/protocols/a2a/envelope.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from picux import __version__
+
+
+Clock = Callable[[], datetime | str]
+
+
+@dataclass(frozen=True)
+class A2AEnvelope:
+    msgId: str
+    kind: str
+    fromAgent: str
+    toAgent: str
+    task: dict[str, Any]
+    caps: tuple[str, ...] = ()
+    payload: dict[str, Any] = field(default_factory=dict)
+    traceId: str = ""
+    createdAt: str = ""
+
+    @classmethod
+    def fromPayload(cls, payload: dict[str, Any], *, clock: Clock | None = None) -> "A2AEnvelope":
+        now = _time(clock or (lambda: datetime.now(timezone.utc)))
+        task = payload.get("task") if isinstance(payload.get("task"), dict) else {}
+        body = payload.get("payload") if isinstance(payload.get("payload"), dict) else {}
+        fromAgent = str(payload.get("fromAgent", "picux") or "picux")
+        toAgent = str(payload.get("toAgent", payload.get("agentId", payload.get("targetAgent", ""))) or "")
+        kind = str(payload.get("kind", "delegate") or "delegate")
+        caps = tuple(_clean(payload.get("caps", payload.get("capabilities", []))))
+        traceId = str(payload.get("traceId", task.get("taskId", "")) or "")
+        base = {
+            "kind": kind,
+            "fromAgent": fromAgent,
+            "toAgent": toAgent,
+            "task": task,
+            "caps": list(caps),
+            "payload": body,
+            "traceId": traceId,
+            "createdAt": now,
+        }
+        msgId = "msg_" + hashlib.sha256(_json(base).encode("utf-8")).hexdigest()[:24]
+        return cls(
+            msgId=msgId,
+            kind=kind,
+            fromAgent=fromAgent,
+            toAgent=toAgent,
+            task=task,
+            caps=caps,
+            payload=body,
+            traceId=traceId,
+            createdAt=now,
+        )
+
+    def toMap(self) -> dict[str, Any]:
+        return {
+            "msgId": self.msgId,
+            "kind": self.kind,
+            "fromAgent": self.fromAgent,
+            "toAgent": self.toAgent,
+            "task": self.task,
+            "caps": list(self.caps),
+            "payload": self.payload,
+            "traceId": self.traceId,
+            "createdAt": self.createdAt,
+        }
+
+
+def createEnvelope(payload: dict[str, Any], *, clock: Clock | None = None) -> dict[str, Any]:
+    envelope = A2AEnvelope.fromPayload(payload, clock=clock).toMap()
+    errors = validateEnvelope(envelope)
+    return {"ok": not errors, "errors": errors, "envelope": envelope}
+
+
+def validateEnvelope(envelope: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if not str(envelope.get("msgId", "") or "").startswith("msg_"):
+        errors.append("invalid:msgId")
+    for key in ("kind", "fromAgent", "toAgent", "createdAt"):
+        if not str(envelope.get(key, "") or ""):
+            errors.append(f"missing:{key}")
+    if not isinstance(envelope.get("task"), dict):
+        errors.append("invalid:task")
+    if not isinstance(envelope.get("payload"), dict):
+        errors.append("invalid:payload")
+    return errors
+
+
+def a2aContract() -> dict[str, Any]:
+    return {
+        "ok": True,
+        "protocol": "picux-a2a",
+        "version": __version__,
+        "transport": "external",
+        "envelope": {
+            "required": ["msgId", "kind", "fromAgent", "toAgent", "task", "createdAt"],
+            "optional": ["caps", "payload", "traceId"],
+            "schema": "schemas/protocols/a2a-envelope.schema.json",
+        },
+        "endpoints": {
+            "contract": "/v1/a2a/contract",
+            "createEnvelope": "/v1/a2a/envelopes",
+            "listEnvelopes": "/v1/a2a/envelopes",
+            "getEnvelope": "/v1/a2a/envelopes/{msgId}",
+            "updateEnvelope": "/v1/a2a/envelopes/{msgId}/update",
+        },
+    }
+
+
+def _clean(value: Any) -> list[str]:
+    if isinstance(value, str):
+        value = [value]
+    if not isinstance(value, (list, tuple, set)):
+        return []
+    return [str(item).strip().lower() for item in value if str(item).strip()]
+
+
+def _time(clock: Clock) -> str:
+    value = clock()
+    if isinstance(value, datetime):
+        return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+    return str(value)
+
+
+def _json(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, ensure_ascii=True, sort_keys=True, separators=(",", ":"))

picux/protocols/mcp/__init__.py

@@ -0,0 +1,7 @@
+"""MCP protocol transport."""
+
+from .client import MCPClient
+from .contract import PicuxMCPContract
+from .server import PicuxMCPServer
+
+__all__ = ["MCPClient", "PicuxMCPContract", "PicuxMCPServer"]

picux/protocols/mcp/client.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from typing import Any
+from urllib import request
+
+from picux.config import resolve_env
+
+
+@dataclass(frozen=True)
+class MCPClient:
+    """Minimal MCP JSON-RPC client using Picux env names with legacy fallback."""
+
+    base_url: str = ""
+    token: str = ""
+    timeout_seconds: int = 20
+
+    @classmethod
+    def fromEnv(cls) -> "MCPClient":
+        return cls(
+            base_url=resolve_env("PICUX_MCP_BASE_URL").value.strip().rstrip("/"),
+            token=resolve_env("PICUX_MCP_TOKEN").value.strip(),
+        )
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.base_url)
+
+    def endpoint(self) -> str:
+        if not self.base_url:
+            raise RuntimeError("mcp_client_disabled")
+        if self.base_url.rstrip("/").endswith("/mcp"):
+            return self.base_url.rstrip("/")
+        return f"{self.base_url.rstrip('/')}/mcp"
+
+    def call(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": f"picux-mcp-{int(time.time() * 1000)}",
+            "method": method,
+            "params": params or {},
+        }
+        headers = {"Content-Type": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        req = request.Request(
+            self.endpoint(),
+            data=json.dumps(payload, ensure_ascii=True).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+        with request.urlopen(req, timeout=max(5, self.timeout_seconds)) as response:
+            body = json.loads(response.read().decode("utf-8"))
+        if not isinstance(body, dict):
+            raise RuntimeError("mcp_invalid_response")
+        if "error" in body:
+            raise RuntimeError(f"mcp_error:{body['error']}")
+        result = body.get("result")
+        if not isinstance(result, dict):
+            raise RuntimeError("mcp_invalid_result")
+        return result
+
+    def listTools(self) -> dict[str, Any]:
+        return self.call("tools/list")
+
+    def callTool(self, name: str, args: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self.call("tools/call", {"name": name, "arguments": args or {}})

picux/protocols/mcp/contract.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any
+
+from picux.api import PicuxApiService
+from picux.contracts import CONTRACT_ENDPOINTS, mcpTools
+
+
+class PicuxMCPContract:
+    """MCP-facing contract for external apps, services, and agents."""
+
+    def __init__(self, *, service: PicuxApiService | None = None) -> None:
+        self.service = service or PicuxApiService()
+        self._tools = {endpoint.mcpTool: endpoint for endpoint in CONTRACT_ENDPOINTS if endpoint.mcpTool}
+
+    def listTools(self) -> dict[str, Any]:
+        return {"tools": mcpTools()}
+
+    def callTool(self, name: str, args: dict[str, Any] | None = None) -> dict[str, Any]:
+        if name not in self._tools:
+            return {"ok": False, "error": "toolNotFound", "tool": name}
+        args = args or {}
+        endpoint = self._tools[name]
+        path = self._path(endpoint.path, args)
+        status, payload = self.service.handle(endpoint.method, path, args, internal=True)
+        if status >= 400:
+            return {"ok": False, "status": status, "payload": payload}
+        return {"ok": True, "status": status, "payload": payload}
+
+    @staticmethod
+    def _path(template: str, args: dict[str, Any]) -> str:
+        path = template
+        for key in (
+            "taskId",
+            "mandateId",
+            "receiptId",
+            "artifactId",
+            "povId",
+            "packId",
+            "agentId",
+            "connectorId",
+            "proxyId",
+            "escrowId",
+            "railId",
+            "challengeId",
+            "resourceId",
+            "adapterId",
+            "cardId",
+            "schemaId",
+            "msgId",
+            "signalId",
+            "eventId",
+            "subId",
+            "deliveryId",
+            "templateId",
+            "playbookId",
+            "sessionId",
+            "threadId",
+            "touchpointId",
+            "actionId",
+            "caseId",
+            "portalSessionId",
+            "portalActionId",
+        ):
+            if "{" + key + "}" in path:
+                path = path.replace("{" + key + "}", str(args.get(key, "")))
+        return path