patchr 0.1.0__py3-none-any.whl

apps/__init__.py

@@ -0,0 +1,2 @@
+"""Picux application entrypoints."""
+

apps/api/__init__.py

@@ -0,0 +1,2 @@
+"""Picux API application."""
+

apps/api/main.py

@@ -0,0 +1,652 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import queue
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+
+from picux.api import PicuxApiService
+
+
+service = PicuxApiService()
+
+
+try:
+    from fastapi import FastAPI, Request
+    from fastapi.responses import JSONResponse, StreamingResponse
+except Exception:  # pragma: no cover - optional dependency
+    FastAPI = None
+    Request = None
+    JSONResponse = None
+    StreamingResponse = None
+
+
+def _json_response(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload, ensure_ascii=True, sort_keys=True).encode("utf-8")
+
+
+def _ndjson_event(payload: dict[str, Any]) -> bytes:
+    return json.dumps(payload, ensure_ascii=True, sort_keys=True).encode("utf-8") + b"\n"
+
+
+def _log_orchestrator(result: dict[str, Any]) -> None:
+    print(
+        "[picux:orchestrator]",
+        json.dumps(
+            {
+                "status": result.get("status"),
+                "route": result.get("route", []),
+                "request": str(result.get("request", ""))[:180],
+                "traceCount": len(result.get("trace", [])) if isinstance(result.get("trace"), list) else 0,
+            },
+            ensure_ascii=True,
+            sort_keys=True,
+        ),
+    )
+    trace = result.get("trace", [])
+    if not isinstance(trace, list):
+        return
+    for event in trace[:30]:
+        if not isinstance(event, dict):
+            continue
+        print(
+            "[picux:orchestrator:trace]",
+            json.dumps(
+                {
+                    "seq": event.get("seq"),
+                    "phase": event.get("phase"),
+                    "name": event.get("name"),
+                    "status": event.get("status"),
+                    "msg": event.get("msg"),
+                    "data": event.get("data", {}),
+                },
+                ensure_ascii=True,
+                sort_keys=True,
+            ),
+        )
+
+
+async def _read_json_body(receive: Any) -> dict[str, Any]:
+    chunks: list[bytes] = []
+    more = True
+    while more:
+        message = await receive()
+        chunks.append(message.get("body", b""))
+        more = bool(message.get("more_body", False))
+    if not chunks:
+        return {}
+    try:
+        payload = json.loads(b"".join(chunks).decode("utf-8") or "{}")
+    except Exception:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+if FastAPI is not None:
+    app = FastAPI(title="Picux Protocol API", version="0.1.0")
+
+    def _contract_openapi() -> dict[str, Any]:
+        return service.handle("GET", "/openapi.json")[1]
+
+    app.openapi = _contract_openapi  # type: ignore[method-assign]
+
+    async def _fastapi_payload(request: Request) -> dict[str, Any]:
+        if request.method != "POST":
+            return {}
+        try:
+            payload = await request.json()
+        except Exception:
+            return {}
+        return payload if isinstance(payload, dict) else {}
+
+    @app.middleware("http")
+    async def authMiddleware(request: Request, call_next: Any) -> Any:
+        status, result = service.authorize(request.method, request.url.path, dict(request.headers))
+        if status >= 400:
+            return JSONResponse(status_code=status, content=result)
+        return await call_next(request)
+
+    @app.get("/healthz")
+    def healthz() -> dict[str, object]:
+        return service.handle("GET", "/healthz")[1]
+
+    @app.get("/runtime")
+    def runtimeSummary() -> dict[str, object]:
+        return service.handle("GET", "/runtime")[1]
+
+    @app.get("/v1/status")
+    def apiStatus() -> dict[str, object]:
+        return service.handle("GET", "/v1/status")[1]
+
+    @app.get("/openapi.json")
+    def openapiJson() -> dict[str, object]:
+        return service.handle("GET", "/openapi.json")[1]
+
+    @app.get("/v1/contract")
+    def contractSummary() -> dict[str, object]:
+        return service.handle("GET", "/v1/contract")[1]
+
+    @app.get("/v1/manifest")
+    def integrationManifest() -> dict[str, object]:
+        return service.handle("GET", "/v1/manifest")[1]
+
+    @app.get("/v1/protocol-map")
+    def protocolMap() -> dict[str, object]:
+        return service.handle("GET", "/v1/protocol-map")[1]
+
+    @app.post("/v1/handshake")
+    def integrationHandshake(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/handshake", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.get("/v1/schemas")
+    def schemaList() -> dict[str, object]:
+        return service.handle("GET", "/v1/schemas")[1]
+
+    @app.get("/v1/schemas/{schemaId}")
+    def schemaGet(schemaId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/schemas/{schemaId}")[1]
+
+    @app.get("/v1/a2a/contract")
+    def a2aContract() -> dict[str, object]:
+        return service.handle("GET", "/v1/a2a/contract")[1]
+
+    @app.get("/v1/a2a/envelopes")
+    def a2aEnvelopeList() -> dict[str, object]:
+        return service.handle("GET", "/v1/a2a/envelopes")[1]
+
+    @app.get("/v1/a2a/envelopes/{msgId}")
+    def a2aEnvelopeGet(msgId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/a2a/envelopes/{msgId}")[1]
+
+    @app.get("/v1/bridge/connectors/ready")
+    def bridgeReadyConnectors() -> dict[str, object]:
+        return service.handle("GET", "/v1/bridge/connectors/ready")[1]
+
+    @app.get("/v1/bridge/connectors")
+    def bridgeConnectorList(request: Request) -> dict[str, object]:
+        return service.handle("GET", str(request.url))[1]
+
+    @app.get("/v1/bridge/connectors/{connectorId}")
+    def bridgeConnectorGet(connectorId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/bridge/connectors/{connectorId}")[1]
+
+    @app.get("/v1/events")
+    def eventList(request: Request) -> dict[str, object]:
+        return service.handle("GET", str(request.url))[1]
+
+    @app.get("/v1/events/{eventId}")
+    def eventGet(eventId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/events/{eventId}")[1]
+
+    @app.get("/v1/event-subscriptions")
+    def eventSubscriptionList(request: Request) -> dict[str, object]:
+        return service.handle("GET", str(request.url))[1]
+
+    @app.get("/v1/event-subscriptions/{subId}")
+    def eventSubscriptionGet(subId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/event-subscriptions/{subId}")[1]
+
+    @app.get("/v1/event-deliveries")
+    def eventDeliveryList(request: Request) -> dict[str, object]:
+        return service.handle("GET", str(request.url))[1]
+
+    @app.get("/v1/event-deliveries/stats")
+    def eventDeliveryStats(request: Request) -> dict[str, object]:
+        return service.handle("GET", str(request.url))[1]
+
+    @app.get("/v1/event-deliveries/ready")
+    def eventDeliveryReady(request: Request) -> dict[str, object]:
+        return service.handle("GET", str(request.url))[1]
+
+    @app.get("/v1/event-deliveries/{deliveryId}")
+    def eventDeliveryGet(deliveryId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/event-deliveries/{deliveryId}")[1]
+
+    @app.get("/v1/event-deliveries/{deliveryId}/chain")
+    def eventDeliveryChain(deliveryId: str, request: Request) -> dict[str, object]:
+        return service.handle("GET", str(request.url))[1]
+
+    @app.post("/mcp")
+    def mcpRpc(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/mcp", payload)[1]
+
+    @app.post("/v1/tools/nlp")
+    def toolNlp(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/tools/nlp", payload)[1]
+
+    @app.post("/v1/tools/imageReader")
+    def toolImageReader(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/tools/imageReader", payload)[1]
+
+    @app.post("/v1/tools/browserReader")
+    def toolBrowserReader(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/tools/browserReader", payload)[1]
+
+    @app.get("/v1/signals/community/entities")
+    def communitySignalEntities() -> dict[str, object]:
+        return service.handle("GET", "/v1/signals/community/entities")[1]
+
+    @app.get("/v1/signals/community")
+    def communitySignalList(request: Request) -> dict[str, object]:
+        return service.handle("GET", str(request.url))[1]
+
+    @app.get("/v1/signals/community/{signalId}")
+    def communitySignalGet(signalId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/signals/community/{signalId}")[1]
+
+    @app.get("/v1/agents")
+    def agentList() -> dict[str, object]:
+        return service.handle("GET", "/v1/agents")[1]
+
+    @app.get("/v1/tasks")
+    def taskList() -> dict[str, object]:
+        return service.handle("GET", "/v1/tasks")[1]
+
+    @app.get("/v1/tasks/{taskId}")
+    def taskGet(taskId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/tasks/{taskId}")[1]
+
+    @app.get("/v1/mandates")
+    def mandateList() -> dict[str, object]:
+        return service.handle("GET", "/v1/mandates")[1]
+
+    @app.get("/v1/mandates/{mandateId}")
+    def mandateGet(mandateId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/mandates/{mandateId}")[1]
+
+    @app.get("/v1/pay/escrows")
+    def escrowList() -> dict[str, object]:
+        return service.handle("GET", "/v1/pay/escrows")[1]
+
+    @app.get("/v1/pay/escrows/{escrowId}")
+    def escrowGet(escrowId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/pay/escrows/{escrowId}")[1]
+
+    @app.get("/v1/agents/{agentId}")
+    def agentGet(agentId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/agents/{agentId}")[1]
+
+    @app.get("/v1/receipts")
+    def receiptList() -> dict[str, object]:
+        return service.handle("GET", "/v1/receipts")[1]
+
+    @app.get("/v1/receipts/{receiptId}")
+    def receiptGet(receiptId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/receipts/{receiptId}")[1]
+
+    @app.get("/v1/audit/pov")
+    def auditPovList() -> dict[str, object]:
+        return service.handle("GET", "/v1/audit/pov")[1]
+
+    @app.get("/v1/audit/pov/{povId}")
+    def auditPovGet(povId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/audit/pov/{povId}")[1]
+
+    @app.get("/v1/audit/evidence")
+    def auditEvidenceList() -> dict[str, object]:
+        return service.handle("GET", "/v1/audit/evidence")[1]
+
+    @app.get("/v1/audit/evidence/{artifactId}")
+    def auditEvidenceGet(artifactId: str) -> dict[str, object]:
+        return service.handle("GET", f"/v1/audit/evidence/{artifactId}")[1]
+
+    @app.post("/v1/tasks")
+    def taskCreate(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/tasks", payload)[1]
+
+    @app.post("/v1/tasks/{taskId}/update")
+    def taskUpdate(taskId: str, payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", f"/v1/tasks/{taskId}/update", payload)[1]
+
+    @app.post("/v1/agents")
+    def agentRegister(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/agents", payload)[1]
+
+    @app.post("/v1/agents/match")
+    def agentMatch(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/agents/match", payload)[1]
+
+    @app.post("/v1/agents/delegate")
+    def agentDelegate(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/agents/delegate", payload)[1]
+
+    @app.post("/v1/bridge/connectors")
+    def bridgeConnectorRegister(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/bridge/connectors", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/bridge/connectors/ready/install")
+    def bridgeReadyConnectorInstall(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/bridge/connectors/ready/install", payload)[1]
+
+    @app.post("/v1/bridge/connectors/match")
+    def bridgeConnectorMatch(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/bridge/connectors/match", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/a2a/envelopes")
+    def a2aEnvelopeCreate(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/a2a/envelopes", payload)[1]
+
+    @app.post("/v1/a2a/envelopes/{msgId}/update")
+    def a2aEnvelopeUpdate(msgId: str, payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", f"/v1/a2a/envelopes/{msgId}/update", payload)[1]
+
+    @app.post("/v1/events")
+    def eventRecord(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/events", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-subscriptions")
+    def eventSubscriptionCreate(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/event-subscriptions", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-subscriptions/{subId}/update")
+    def eventSubscriptionUpdate(subId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/event-subscriptions/{subId}/update", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries")
+    def eventDeliveryCreate(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/event-deliveries", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/claim")
+    def eventDeliveryClaim(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/event-deliveries/claim", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/claimBatch")
+    def eventDeliveryClaimBatch(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/event-deliveries/claimBatch", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/sweep")
+    def eventDeliverySweep(payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", "/v1/event-deliveries/sweep", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/{deliveryId}/retry")
+    def eventDeliveryRetry(deliveryId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/event-deliveries/{deliveryId}/retry", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/{deliveryId}/fail")
+    def eventDeliveryFail(deliveryId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/event-deliveries/{deliveryId}/fail", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/{deliveryId}/complete")
+    def eventDeliveryComplete(deliveryId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/event-deliveries/{deliveryId}/complete", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/{deliveryId}/cancel")
+    def eventDeliveryCancel(deliveryId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/event-deliveries/{deliveryId}/cancel", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/{deliveryId}/lease")
+    def eventDeliveryLease(deliveryId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/event-deliveries/{deliveryId}/lease", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/{deliveryId}/release")
+    def eventDeliveryRelease(deliveryId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/event-deliveries/{deliveryId}/release", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/event-deliveries/{deliveryId}/update")
+    def eventDeliveryUpdate(deliveryId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/event-deliveries/{deliveryId}/update", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/events/{eventId}/ack")
+    def eventAck(eventId: str, payload: dict[str, Any]) -> Any:
+        status, result = service.handle("POST", f"/v1/events/{eventId}/ack", payload)
+        return JSONResponse(status_code=status, content=result)
+
+    @app.post("/v1/hunt/discover")
+    def huntDiscover(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/hunt/discover", payload)[1]
+
+    @app.post("/v1/orchestrator/run")
+    def orchestratorRun(payload: dict[str, Any]) -> dict[str, object]:
+        if payload.get("stream") and StreamingResponse is not None:
+            return StreamingResponse(_orchestrator_stream(payload), media_type="application/x-ndjson")  # type: ignore[return-value]
+        result = service.handle("POST", "/v1/orchestrator/run", payload)[1]
+        _log_orchestrator(result)
+        return result
+
+    @app.post("/v1/benchmarks/local")
+    def benchmarkLocal(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/benchmarks/local", payload)[1]
+
+    @app.post("/v1/tasks/{taskId}/resolve")
+    def taskResolve(taskId: str, payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", f"/v1/tasks/{taskId}/resolve", payload)[1]
+
+    @app.post("/v1/mandates")
+    def mandateCreate(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/mandates", payload)[1]
+
+    @app.post("/v1/mandates/{mandateId}/verify")
+    def mandateVerify(mandateId: str, payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", f"/v1/mandates/{mandateId}/verify", payload)[1]
+
+    @app.post("/v1/pay/escrows")
+    def escrowCreate(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/pay/escrows", payload)[1]
+
+    @app.post("/v1/pay/escrows/{escrowId}/update")
+    def escrowUpdate(escrowId: str, payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", f"/v1/pay/escrows/{escrowId}/update", payload)[1]
+
+    @app.post("/v1/pay/settle")
+    def paySettle(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/pay/settle", payload)[1]
+
+    @app.post("/v1/audit/evidence")
+    def auditEvidence(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/audit/evidence", payload)[1]
+
+    @app.post("/v1/audit/pov")
+    def auditPov(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/audit/pov", payload)[1]
+
+    @app.post("/v1/audit/receipts/verify")
+    def auditReceiptVerify(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/audit/receipts/verify", payload)[1]
+
+    @app.post("/v1/audit/chain/verify")
+    def auditChainVerify(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/audit/chain/verify", payload)[1]
+
+    @app.post("/v1/signals/community")
+    def communitySignal(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/signals/community", payload)[1]
+
+    @app.post("/v1/signals/community/analyze")
+    def communitySignalAnalyze(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/signals/community/analyze", payload)[1]
+
+    @app.post("/v1/signals/community/launch-task")
+    def communitySignalLaunchTask(payload: dict[str, Any]) -> dict[str, object]:
+        return service.handle("POST", "/v1/signals/community/launch-task", payload)[1]
+
+    @app.api_route("/{path:path}", methods=["GET", "POST"])
+    async def contractFallback(path: str, request: Request) -> Any:
+        target = str(request.url)
+        payload = await _fastapi_payload(request)
+        status, result = service.handle(request.method, target, payload, headers=dict(request.headers))
+        if request.method == "POST" and request.url.path == "/v1/orchestrator/run":
+            _log_orchestrator(result)
+        return JSONResponse(status_code=status, content=result)
+
+else:
+
+    async def app(scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope.get("type") != "http":
+            return
+        path = scope.get("path", "")
+        query = scope.get("query_string", b"").decode("latin1")
+        target = f"{path}?{query}" if query else path
+        method = scope.get("method", "GET")
+        if method == "POST":
+            payload = await _read_json_body(receive)
+        else:
+            payload = {}
+        if method == "POST" and path == "/v1/orchestrator/run" and payload.get("stream"):
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 200,
+                    "headers": [(b"content-type", b"application/x-ndjson")],
+                }
+            )
+
+            def emit(event: dict[str, Any]) -> None:
+                events.put(event)
+
+            def run() -> None:
+                try:
+                    result = service.runOrchestrator(payload, onEvent=emit)
+                    _log_orchestrator(result)
+                    events.put({"type": "final", "result": result})
+                except Exception as exc:
+                    events.put({"type": "error", "error": str(exc)[:500]})
+                finally:
+                    events.put(None)
+
+            events: "queue.Queue[dict[str, Any] | None]" = queue.Queue()
+            threading.Thread(target=run, daemon=True).start()
+            while True:
+                event = await asyncio.to_thread(events.get)
+                if event is None:
+                    break
+                await send({"type": "http.response.body", "body": _ndjson_event(event), "more_body": True})
+            await send({"type": "http.response.body", "body": b"", "more_body": False})
+            return
+        status, result = service.handle(method, target, payload, headers=_scope_headers(scope))
+        if method == "POST" and path == "/v1/orchestrator/run":
+            _log_orchestrator(result)
+        body = _json_response(result)
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status,
+                "headers": [(b"content-type", b"application/json")],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})
+
+
+class _LocalHandler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:
+        status, payload = service.handle("GET", self.path, headers=dict(self.headers.items()))
+        body = _json_response(payload)
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_POST(self) -> None:
+        length = int(self.headers.get("Content-Length", "0") or "0")
+        try:
+            payload = json.loads(self.rfile.read(length).decode("utf-8") or "{}")
+        except Exception:
+            payload = {}
+        payload = payload if isinstance(payload, dict) else {}
+        if self.path.split("?", 1)[0] == "/v1/orchestrator/run" and payload.get("stream"):
+            self._stream_orchestrator(payload)
+            return
+        status, result = service.handle(
+            "POST",
+            self.path,
+            payload,
+            headers=dict(self.headers.items()),
+        )
+        if self.path.split("?", 1)[0] == "/v1/orchestrator/run":
+            _log_orchestrator(result)
+        body = _json_response(result)
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format: str, *args: Any) -> None:
+        return
+
+    def _stream_orchestrator(self, payload: dict[str, Any]) -> None:
+        self.send_response(200)
+        self.send_header("Content-Type", "application/x-ndjson")
+        self.send_header("Cache-Control", "no-cache")
+        self.end_headers()
+        closed = False
+
+        def emit(event: dict[str, Any]) -> None:
+            nonlocal closed
+            if closed:
+                return
+            try:
+                self.wfile.write(_ndjson_event(event))
+                self.wfile.flush()
+            except (BrokenPipeError, ConnectionResetError):
+                closed = True
+
+        try:
+            result = service.runOrchestrator(payload, onEvent=emit)
+            if not closed:
+                _log_orchestrator(result)
+                emit({"type": "final", "result": result})
+        except Exception as exc:
+            if not closed:
+                emit({"type": "error", "error": str(exc)[:500]})
+
+
+def _orchestrator_stream(payload: dict[str, Any]):
+    events: "queue.Queue[dict[str, Any] | None]" = queue.Queue()
+
+    def emit(event: dict[str, Any]) -> None:
+        events.put(event)
+
+    def run() -> None:
+        try:
+            result = service.runOrchestrator(payload, onEvent=emit)
+            _log_orchestrator(result)
+            events.put({"type": "final", "result": result})
+        except Exception as exc:
+            events.put({"type": "error", "error": str(exc)[:500]})
+        finally:
+            events.put(None)
+
+    threading.Thread(target=run, daemon=True).start()
+    while True:
+        event = events.get()
+        if event is None:
+            break
+        yield _ndjson_event(event)
+
+
+def main() -> None:
+    service.runtime.assertBootable()
+    server = HTTPServer(("127.0.0.1", 8088), _LocalHandler)
+    print("Picux API scaffold listening on http://127.0.0.1:8088")
+    server.serve_forever()
+
+
+def _scope_headers(scope: dict[str, Any]) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    for key, value in scope.get("headers", []):
+        headers[key.decode("latin1")] = value.decode("latin1")
+    return headers
+
+
+if __name__ == "__main__":
+    main()

apps/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Benchmark command entrypoints."""

apps/benchmarks/main.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import argparse
+import json
+
+from picux.benchmarks import LocalBenchmark
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run Picux local protocol benchmarks.")
+    parser.add_argument("--iterations", type=int, default=100)
+    parser.add_argument("--pretty", action="store_true")
+    args = parser.parse_args()
+
+    report = LocalBenchmark(iterations=args.iterations).run()
+    print(json.dumps(report, ensure_ascii=True, sort_keys=True, indent=2 if args.pretty else None))
+
+
+if __name__ == "__main__":
+    main()