beeos-cloud-harness-sdk 1.0.0__py3-none-any.whl

beeos_cloud_harness_sdk/__init__.py

@@ -0,0 +1,283 @@
+"""Production BeeOS Harness SDK for custom agent harnesses (OpenClaw, Hermes, and others)."""
+from __future__ import annotations
+import json, urllib.error, urllib.parse, urllib.request
+from collections.abc import Callable
+from typing import Any, get_args
+
+from ._generated.models import RuntimeMessagePatch, RuntimeMethod
+from ._generated.operations import OPERATIONS, operation_path
+
+RUNTIME_METHODS: list[str] = list(get_args(RuntimeMethod))
+
+# Cloud chat delivers every user prompt as this runtime method. The bound reply
+# row is pre-created by Cloud in `streaming`; the agent converges it.
+CHAT_PROMPT_METHOD = "session/prompt"
+
+class BeeOSAgentError(RuntimeError):
+    def __init__(self, status: int, code: str, message: str):
+        super().__init__(message)
+        self.status, self.code = status, code
+
+class BeeOSAgentRuntime:
+    def __init__(self, agent_gateway_url: str, message_service_url: str, instance_id: str, agent_id: str, token: str | Callable[[], str], framework: str = "custom", transport=None):
+        if not all([agent_gateway_url, message_service_url, instance_id, agent_id, token]):
+            raise ValueError("agent runtime requires gateway, message service, instance, agent and token")
+        self.agent_gateway_url = agent_gateway_url.rstrip("/") + "/"
+        self.message_service_url = message_service_url.rstrip("/") + "/"
+        self.instance_id = instance_id
+        self.agent_id = agent_id
+        self._token = token
+        self.framework = framework
+        self._transport = transport
+        self._closed = False
+        self.on_chat_message = None
+        self.on_chat_cancel = None
+        self.on_runtime_method = None
+        self.agent = _Agent(self)
+        self.messages = _Messages(self)
+        self.chat = _Chat(self)
+        self.files = _Files(self)
+        self.canvas = _Canvas(self)
+        self.a2a = _A2a(self)
+        self.messaging = _Messaging(self)
+
+    def token(self) -> str:
+        return self._token() if callable(self._token) else self._token
+
+    def register(self, *, on_chat_message=None, on_chat_cancel=None, on_runtime_method=None):
+        self.on_chat_message = on_chat_message
+        self.on_chat_cancel = on_chat_cancel
+        self.on_runtime_method = on_runtime_method
+
+    def request(self, base: str, method: str, path: str, json_body=None, headers=None):
+        if self._closed:
+            raise BeeOSAgentError(409, "runtime_closed", "BeeOSAgentRuntime is closed")
+        root = self.agent_gateway_url if base == "gateway" else self.message_service_url
+        url = urllib.parse.urljoin(root, path.lstrip("/"))
+        key = self.token()
+        req_headers = {
+            "Authorization": key if " " in key else f"Bearer {key}",
+            "Accept": "application/json",
+            "X-BeeOS-Instance-ID": self.instance_id,
+            "X-BeeOS-Agent-ID": self.agent_id,
+        }
+        if headers:
+            req_headers.update(headers)
+        data = None
+        if json_body is not None:
+            req_headers["Content-Type"] = "application/json"
+            data = json.dumps(json_body).encode()
+        if self._transport:
+            status, raw, _resp = self._transport(method, url, req_headers, data)
+            if status >= 400:
+                raise BeeOSAgentError(status, "agent_backend_unavailable", raw.decode() if isinstance(raw, (bytes, bytearray)) else str(raw))
+            if status == 204 or not raw:
+                return None
+            return json.loads(raw)
+        req = urllib.request.Request(url, data=data, headers=req_headers, method=method)
+        try:
+            with urllib.request.urlopen(req) as resp:
+                raw = resp.read()
+                if resp.status == 204 or not raw:
+                    return None
+                return json.loads(raw.decode())
+        except urllib.error.HTTPError as err:
+            payload = err.read().decode()
+            code, message = "agent_backend_unavailable", err.reason
+            try:
+                parsed = json.loads(payload)
+                code, message = parsed.get("code", code), parsed.get("message", message)
+            except Exception:
+                pass
+            raise BeeOSAgentError(err.code, code, message) from err
+
+    def _call(self, operation_id: str, json_body=None, headers=None, **path_params):
+        method, _path, service = OPERATIONS[operation_id]
+        base = "gateway" if service == "agent-gateway" else "message"
+        return self.request(base, method, operation_path(operation_id, **path_params), json_body, headers)
+
+    def dispatch_chat_message(self, event: dict):
+        if self.on_chat_message:
+            return self.on_chat_message(event)
+
+    def dispatch_chat_cancel(self, event: dict):
+        if self.on_chat_cancel:
+            return self.on_chat_cancel(event)
+
+    def dispatch_runtime_method(self, method: str, params: dict | None = None):
+        if method not in RUNTIME_METHODS:
+            raise BeeOSAgentError(400, "unsupported_runtime_method", method)
+        if method == CHAT_PROMPT_METHOD and not self.on_runtime_method:
+            return self.dispatch_session_prompt(params or {})
+        if not self.on_runtime_method:
+            raise BeeOSAgentError(501, "runtime_method_unhandled", method)
+        return self.on_runtime_method(method, params or {})
+
+    def dispatch_session_prompt(self, params: dict):
+        """Cloud chat prompt -> the agent's chat handler (same event shape)."""
+        prompt = extract_session_prompt(params, self.agent_id)
+        if prompt is None:
+            raise BeeOSAgentError(400, "invalid_session_prompt", CHAT_PROMPT_METHOD)
+        return self.dispatch_chat_message(prompt)
+
+    def consume_envelope(self, envelope: dict):
+        kind = envelope.get("type") or (envelope.get("message") or {}).get("type") or ""
+        if kind == "chat_cancel":
+            content = envelope.get("content") or {}
+            return self.dispatch_chat_cancel({
+                "conversationId": envelope.get("conversationId") or envelope.get("conversation_id") or "",
+                "targetMessageId": envelope.get("replyTo") or envelope.get("reply_to") or content.get("target_message_id") or "",
+                "agentId": self.agent_id,
+            })
+        prompt = extract_chat_prompt(envelope, self.agent_id)
+        if not prompt or not prompt.get("messageId") or not prompt.get("channelId"):
+            return None
+        return self.dispatch_chat_message({
+            "conversationId": prompt["channelId"],
+            "messageId": prompt["messageId"],
+            "agentId": self.agent_id,
+            "text": prompt["message"],
+            "channelId": prompt["channelId"],
+            "sessionKey": prompt.get("sessionKey"),
+            "files": prompt.get("files") or [],
+        })
+
+    def close(self):
+        self._closed = True
+        self.on_chat_message = self.on_chat_cancel = self.on_runtime_method = None
+
+def extract_chat_prompt(envelope: dict, local_agent_id: str = "") -> dict | None:
+    inner = envelope.get("message") or envelope
+    content = inner.get("content") or {}
+    if not isinstance(content, dict):
+        content = {}
+    text = content.get("message") or envelope.get("body") or ""
+    if not text and isinstance(content.get("parts"), list):
+        text = "\n".join(part.get("text", "") for part in content["parts"] if isinstance(part, dict) and part.get("type") == "text")
+    if not text:
+        return None
+    channel_id = inner.get("conversationId") or envelope.get("conversationId") or envelope.get("conversation_id") or content.get("channel_id")
+    context_id = content.get("context_id") or (content.get("metadata") or {}).get("context_id")
+    message_id = inner.get("id") or envelope.get("id")
+    source = "a2a" if inner.get("type") == "agent_request" or envelope.get("type") == "agent_request" else "invoke"
+    session_key = content.get("session_key") or f"agent:{local_agent_id}:{source}:{'ctx-' + context_id if context_id else 'ch-' + channel_id if channel_id else 'anon'}"
+    files = [item for item in (content.get("files") or []) if isinstance(item, str)]
+    if isinstance(content.get("parts"), list):
+        files.extend(part.get("file_url") for part in content["parts"] if isinstance(part, dict) and part.get("file_url"))
+    return {"message": text, "files": [item for item in files if item], "channelId": channel_id, "contextId": context_id, "sessionKey": session_key, "messageId": message_id}
+
+def extract_session_prompt(params: dict, local_agent_id: str = "") -> dict | None:
+    """Normalize Cloud chat ``session/prompt`` params into a chat event.
+
+    Returns None when the task binding Cloud guarantees is incomplete, so the
+    caller fails the operation instead of writing to an unbound reply row.
+    """
+    if not isinstance(params, dict):
+        return None
+    conversation_id = str(params.get("conversationId") or "")
+    reply_message_id = str(params.get("replyMessageId") or "")
+    message_id = str(params.get("taskRequestMessageId") or "")
+    run_id = str(params.get("runtimeRunId") or params.get("taskId") or "")
+    if not conversation_id or not reply_message_id or not message_id or not run_id:
+        return None
+    raw_parts = params.get("parts") if isinstance(params.get("parts"), list) else []
+    parts = [part for part in raw_parts if isinstance(part, dict)]
+    text = "\n".join(str(part.get("text") or "") for part in parts if part.get("type") == "text").strip()
+    files = [str(part["blobRef"]) for part in parts if part.get("blobRef")]
+    agent_id = str(params.get("platformAgentId") or local_agent_id)
+    return {
+        "conversationId": conversation_id,
+        "channelId": conversation_id,
+        "messageId": message_id,
+        "replyMessageId": reply_message_id,
+        "runtimeRunId": run_id,
+        "agentId": agent_id,
+        "text": text,
+        "files": files,
+        "modelOverrideId": str(params.get("modelOverrideId") or "") or None,
+        "sessionKey": f"agent:{agent_id}:cloud-chat:ch-{conversation_id}",
+    }
+
+
+class _Chat:
+    """Cloud chat reply convergence over the current runtime lease."""
+
+    def __init__(self, runtime: BeeOSAgentRuntime):
+        self.runtime = runtime
+
+    def patch_reply(self, conversation_id: str, reply_message_id: str, body: RuntimeMessagePatch, operation_key: str = ""):
+        if not conversation_id or not reply_message_id:
+            raise BeeOSAgentError(400, "invalid_chat_reply", "chat reply requires conversationId and replyMessageId")
+        headers = {"Idempotency-Key": operation_key} if operation_key else None
+        return self.runtime._call("runtimeConversationMessagePatch", body, headers, conversationId=conversation_id, messageId=reply_message_id)
+
+    def complete_reply(self, conversation_id: str, reply_message_id: str, text: str, operation_key: str = ""):
+        return self.patch_reply(
+            conversation_id, reply_message_id,
+            {"body": text, "parts": [{"type": "text", "text": text}], "state": "completed", "stop_reason": "end_turn"},
+            operation_key)
+
+    def fail_reply(self, conversation_id: str, reply_message_id: str, text: str = "", operation_key: str = ""):
+        return self.patch_reply(
+            conversation_id, reply_message_id,
+            {"body": text, "state": "failed", "stop_reason": "error"},
+            operation_key)
+
+
+class _Agent:
+    def __init__(self, runtime: BeeOSAgentRuntime):
+        self.runtime = runtime
+    def get(self):
+        return self.runtime._call("agentGet", agentId=self.runtime.agent_id)
+    def update_exposure(self, patch, resource_version):
+        return self.runtime._call("agentUpdate", patch, {"If-Match": f'"{resource_version}"'}, agentId=self.runtime.agent_id)
+    def sync(self, input):
+        return self.runtime._call("agentSync", input)
+
+class _Messages:
+    def __init__(self, runtime: BeeOSAgentRuntime):
+        self.runtime = runtime
+    def send(self, conversation_id, input):
+        return self.runtime._call("conversationMessageSend", input, conversationId=conversation_id)
+    def reply(self, conversation_id: str, inbound_message_id: str, text: str):
+        if not conversation_id or not inbound_message_id:
+            raise BeeOSAgentError(400, "invalid_agent_reply", "agent_reply requires conversationId and inbound messageId")
+        return self.send(conversation_id, {"type": "agent_reply", "replyTo": inbound_message_id, "reply_to": inbound_message_id, "content": {"text": text}, "sender": self.runtime.instance_id})
+    def list(self, conversation_id):
+        return self.runtime._call("conversationMessagesList", conversationId=conversation_id)
+    def consume_envelope(self, envelope: dict):
+        return self.runtime.consume_envelope(envelope)
+
+class _Files:
+    def __init__(self, runtime: BeeOSAgentRuntime):
+        self.runtime = runtime
+    def list(self):
+        return self.runtime._call("agentFilesList")
+    def presign(self, input):
+        return self.runtime._call("agentFilePresign", input)
+    def confirm(self, input):
+        return self.runtime._call("agentFileConfirm", input)
+    def resolve(self, file_id):
+        return self.runtime._call("agentFileResolve", fileId=file_id)
+
+class _Canvas:
+    def __init__(self, runtime: BeeOSAgentRuntime):
+        self.runtime = runtime
+    def token(self, input=None):
+        return self.runtime._call("canvasTokenCreate", input if input is not None else {})
+
+class _A2a:
+    def __init__(self, runtime: BeeOSAgentRuntime):
+        self.runtime = runtime
+    def discover(self):
+        return self.runtime._call("a2aDiscover")
+    def call(self, agent_id, input):
+        return self.runtime._call("a2aJsonRpc", input, agentId=agent_id)
+    def get_task(self, task_id):
+        return self.runtime._call("a2aTaskGet", taskId=task_id)
+
+class _Messaging:
+    def __init__(self, runtime: BeeOSAgentRuntime):
+        self.runtime = runtime
+    def token(self, input=None):
+        return self.runtime._call("messagingTokenCreate", input if input is not None else {})

beeos_cloud_harness_sdk/_generated/__init__.py

@@ -0,0 +1 @@
+"""Generated by sdks/codegen/gen.mjs from sdks/products/harness/spec/harness.openapi.yaml. Do not edit."""

beeos_cloud_harness_sdk/_generated/models.py

@@ -0,0 +1,97 @@
+# generated by datamodel-codegen:
+#   filename:  harness.openapi.yaml
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypeAlias, TypedDict
+
+
+class JsonObject(TypedDict):
+    pass
+
+
+RuntimeMethod: TypeAlias = Literal[
+    'agent/create',
+    'agent/update',
+    'agent/delete',
+    'agent/applyTemplate',
+    'skills/list',
+    'skills/install',
+    'skills/update',
+    'skills/uninstall',
+    'models/list',
+    'cron/list',
+    'cron/status',
+    'cron/add',
+    'cron/update',
+    'cron/remove',
+    'cron/run',
+    'cron/runs',
+    'mcp/list',
+    'mcp/prepare',
+    'mcp/set',
+    'mcp/unset',
+    'session/set_mode',
+    'session/set_model',
+    'session/clear',
+    'session/cancel',
+    'session/prompt',
+    'canvas/toggle',
+    'canvas/clear',
+    'canvas/reference',
+    'canvas/dimensions',
+]
+
+
+class RuntimeDeliveriesReadRequest(TypedDict):
+    schemaVersion: Literal[1]
+    maxCount: int
+    blockMs: int
+
+
+class RuntimeDeliveryIdsRequest(TypedDict):
+    schemaVersion: Literal[1]
+    deliveryIds: list[str]
+
+
+class RuntimeOperationAppendRequest(TypedDict):
+    schemaVersion: Literal[1]
+    type: str
+    payload: Any
+
+
+class RuntimeConversationSyncRequest(TypedDict):
+    schemaVersion: Literal[1]
+    operationId: str
+    runtimeSessionId: str
+    runtimeSessionKey: NotRequired[str]
+    title: NotRequired[str]
+
+
+class RuntimeMessagePatch(TypedDict):
+    body: NotRequired[str]
+    body_append: NotRequired[str]
+    body_from: NotRequired[int]
+    parts: NotRequired[list[JsonObject]]
+    state: NotRequired[str]
+    stop_reason: NotRequired[str]
+
+
+class TerminalAgentAuthFrame(TypedDict):
+    type: Literal['agent_auth']
+    instance_id: str
+    service: Literal['terminal']
+    public_key: str
+    timestamp: int
+    nonce: str
+    signature: str
+    runtimeLeaseCredential: str
+    handlerIdentity: str
+    runtimeEpoch: str
+    leaseId: str
+
+
+class CanvasRelayConnect(TypedDict):
+    path: Literal['/ws/agent']
+    agentIdQuery: NotRequired[str]
+    tokenQuery: NotRequired[str]

beeos_cloud_harness_sdk/_generated/operations.py

@@ -0,0 +1,70 @@
+# Generated by sdks/codegen/gen.mjs from sdks/products/harness/spec/harness.openapi.yaml. Do not edit.
+import re
+from urllib.parse import quote
+
+OPERATIONS: dict[str, tuple[str, str, str]] = {
+    "runtimeRegister": ("POST", "/api/v1/runtime/registrations", "agent-gateway"),
+    "runtimeHeartbeat": ("POST", "/api/v1/runtime/registrations/{registrationId}/heartbeat", "agent-gateway"),
+    "runtimeRealtimeTokenCreate": ("POST", "/api/v1/runtime/realtime/token", "message-service"),
+    "runtimeConversationSync": ("POST", "/api/v1/runtime/conversations", "message-service"),
+    "runtimeConversationMessagesList": ("GET", "/api/v1/runtime/conversations/{conversationId}/messages", "message-service"),
+    "runtimeConversationMessageCreate": ("POST", "/api/v1/runtime/conversations/{conversationId}/messages", "message-service"),
+    "runtimeConversationMessageGet": ("GET", "/api/v1/runtime/conversations/{conversationId}/messages/{messageId}", "message-service"),
+    "runtimeConversationMessagePatch": ("PATCH", "/api/v1/runtime/conversations/{conversationId}/messages/{messageId}", "message-service"),
+    "runtimeConversationRunStart": ("POST", "/api/v1/runtime/conversations/{conversationId}/runs/start", "message-service"),
+    "runtimeConversationRunFinish": ("POST", "/api/v1/runtime/conversations/{conversationId}/runs/finish", "message-service"),
+    "runtimeDeliveriesRead": ("POST", "/api/v1/runtime/deliveries/read", "message-service"),
+    "runtimeDeliveriesRenew": ("POST", "/api/v1/runtime/deliveries/renew", "message-service"),
+    "runtimeDeliveriesAck": ("POST", "/api/v1/runtime/deliveries/ack", "message-service"),
+    "runtimeOperationHistoryGet": ("GET", "/api/v1/runtime/operations/{operationId}/history", "message-service"),
+    "runtimeOperationMessageAppend": ("POST", "/api/v1/runtime/operations/{operationId}/messages", "message-service"),
+    "conversationMessagesList": ("GET", "/api/v2/conversations/{conversationId}/messages", "message-service"),
+    "conversationMessageSend": ("POST", "/api/v2/conversations/{conversationId}/messages", "message-service"),
+    "agentGet": ("GET", "/api/v1/agents/{agentId}", "agent-gateway"),
+    "agentUpdate": ("PATCH", "/api/v1/agents/{agentId}", "agent-gateway"),
+    "agentSync": ("POST", "/api/v1/agents/sync", "agent-gateway"),
+    "agentFilesList": ("GET", "/api/v1/agent/files", "agent-gateway"),
+    "agentFilePresign": ("POST", "/api/v1/agent/files/presign", "agent-gateway"),
+    "agentFileConfirm": ("POST", "/api/v1/agent/files/confirm", "agent-gateway"),
+    "agentFileResolve": ("GET", "/api/v1/agent/files/{fileId}/resolve", "agent-gateway"),
+    "canvasTokenCreate": ("POST", "/api/v1/canvas/token", "agent-gateway"),
+    "a2aDiscover": ("GET", "/api/v1/a2a/discover", "agent-gateway"),
+    "a2aJsonRpc": ("POST", "/api/v1/a2a/{agentId}/jsonrpc", "agent-gateway"),
+    "a2aTaskGet": ("GET", "/api/v1/a2a/tasks/{taskId}", "agent-gateway"),
+    "messagingTokenCreate": ("POST", "/api/v1/messaging/token", "agent-gateway"),
+    "runtimeHistoryBoundaryPrepare": ("POST", "/api/v1/runtime/conversations/{conversationId}/history-boundary/prepare", "message-service"),
+    "runtimeHistoryBoundaryResetting": ("POST", "/api/v1/runtime/conversations/{conversationId}/history-boundary/resetting", "message-service"),
+    "runtimeHistoryBoundaryResetDone": ("POST", "/api/v1/runtime/conversations/{conversationId}/history-boundary/reset_done", "message-service"),
+    "runtimeHistoryBoundaryCommit": ("POST", "/api/v1/runtime/conversations/{conversationId}/history-boundary/commit", "message-service"),
+    "runtimeHistoryBoundaryAbort": ("POST", "/api/v1/runtime/conversations/{conversationId}/history-boundary/abort", "message-service"),
+    "runtimeHistoryBoundaryReconcile": ("POST", "/api/v1/runtime/conversations/{conversationId}/history-boundary/reconcile", "message-service"),
+    "runtimeConversationMetadataModel": ("POST", "/api/v1/runtime/conversations/{conversationId}/metadata/model", "message-service"),
+    "runtimeConversationCronDelivery": ("POST", "/api/v1/runtime/conversations/{conversationId}/deliveries/cron", "message-service"),
+    "runtimeClaimNext": ("POST", "/api/v1/runtime/claims/next", "message-service"),
+    "runtimeClaimExact": ("POST", "/api/v1/runtime/operations/{operationId}/claims", "message-service"),
+    "runtimeClaimRenew": ("POST", "/api/v1/runtime/operations/{operationId}/claims/renew", "message-service"),
+    "runtimeClaimRelease": ("POST", "/api/v1/runtime/operations/{operationId}/claims/release", "message-service"),
+    "runtimeResourceRedeem": ("POST", "/api/v1/internal/runtime/operations/{operationId}/resources/{kind}/{resourceRef}/redeem", "agent-gateway"),
+    "runtimeOutputFilePresign": ("POST", "/api/v1/internal/runtime/operations/{operationId}/output-files/presign", "agent-gateway"),
+    "runtimeOutputFileConfirm": ("POST", "/api/v1/internal/runtime/operations/{operationId}/output-files/confirm", "agent-gateway"),
+    "runtimeInputFilesResolve": ("POST", "/api/v1/internal/runtime/operations/{operationId}/input-files/resolve", "agent-gateway"),
+    "agentTemplateOriginReport": ("POST", "/api/v1/agents/{agentId}/template-origin", "agent-gateway"),
+    "channelCreate": ("POST", "/api/v1/channels", "agent-gateway"),
+    "a2aTaskComplete": ("POST", "/api/v1/a2a/tasks/{taskId}/complete", "agent-gateway"),
+    "agentEventPublish": ("POST", "/api/v1/agent/events", "agent-gateway"),
+    "bridgeConfigGet": ("GET", "/api/v1/bridge/config", "agent-gateway"),
+    "agentConnectorMcp": ("POST", "/api/v1/agent/connectors/mcp", "agent-gateway"),
+    "automationList": ("GET", "/api/v1/automations", "agent-gateway"),
+    "automationCreate": ("POST", "/api/v1/automations", "agent-gateway"),
+    "automationWebhookCreate": ("POST", "/api/v1/automations/webhooks", "agent-gateway"),
+    "automationGet": ("GET", "/api/v1/automations/{automationId}", "agent-gateway"),
+    "automationRunsList": ("GET", "/api/v1/automations/{automationId}/runs", "agent-gateway"),
+    "automationRunCreate": ("POST", "/api/v1/automations/{automationId}/runs", "agent-gateway"),
+    "automationRunGet": ("GET", "/api/v1/automations/{automationId}/runs/{runId}", "agent-gateway"),
+}
+
+
+def operation_path(operation_id: str, **params: object) -> str:
+    """Expand an operation's path template; every value is percent-encoded."""
+    template = OPERATIONS[operation_id][1]
+    return re.sub(r"\{(\w+)\}", lambda match: quote(str(params[match.group(1)]), safe=""), template)

beeos_cloud_harness_sdk/canvas_relay.py

@@ -0,0 +1,112 @@
+"""Canvas relay WebSocket URL, upgrade headers, and frames. Socket I/O is injected.
+
+Mirror of ``src/canvas-relay.ts``. Yjs payload bytes stay with the harness.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Protocol
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from beeos_cloud_harness_sdk.identity import AgentKeyPair, agent_auth_headers
+
+CANVAS_RELAY_PATH = "/ws/agent"
+
+
+def canvas_relay_websocket_url(
+    relay_url: str, *, agent_id: str | None = None, token: str | None = None,
+) -> str:
+    """``{relay}/ws/agent``. An existing path prefix is kept. Never ``/ws/{canvasId}``."""
+    base = relay_url.strip().rstrip("/")
+    if not base:
+        raise ValueError("empty canvas relay url")
+    if base.startswith("https://"):
+        base = "wss://" + base[len("https://"):]
+    elif base.startswith("http://"):
+        base = "ws://" + base[len("http://"):]
+    elif not (base.startswith("ws://") or base.startswith("wss://")):
+        base = "wss://" + base
+    if not base.endswith(CANVAS_RELAY_PATH):
+        base = base + CANVAS_RELAY_PATH
+    parts = urlsplit(base)
+    query = dict(parse_qsl(parts.query, keep_blank_values=True))
+    if agent_id:
+        query["agentId"] = agent_id
+    if token:
+        query["token"] = token
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, urlencode(query), ""))
+
+
+def canvas_relay_upgrade_headers(keys: AgentKeyPair) -> dict[str, str]:
+    return agent_auth_headers("GET", CANVAS_RELAY_PATH, keys)
+
+
+def canvas_relay_join_frame(canvas_id: str) -> str:
+    return json.dumps({"type": "join", "canvasId": canvas_id}, separators=(",", ":"))
+
+
+def canvas_relay_leave_frame(canvas_id: str) -> str:
+    return json.dumps({"type": "leave", "canvasId": canvas_id}, separators=(",", ":"))
+
+
+def encode_canvas_relay_binary(canvas_id: str, payload: bytes) -> bytes:
+    encoded = canvas_id.encode("utf-8")
+    if not encoded or len(encoded) > 255:
+        raise ValueError("canvas id length must be 1..255 bytes")
+    return bytes((len(encoded),)) + encoded + payload
+
+
+class CanvasRelaySocket(Protocol):
+    def send(self, data: str | bytes) -> None: ...
+    def close(self) -> None: ...
+    async def wait_open(self) -> None: ...
+
+
+class CanvasRelayClient:
+    def __init__(
+        self,
+        *,
+        relay_url: str,
+        keys: AgentKeyPair,
+        agent_id: str | None = None,
+        token: str | None = None,
+        socket_factory: Callable[[str, dict[str, str]], CanvasRelaySocket] | None = None,
+    ) -> None:
+        self._relay_url = relay_url
+        self._keys = keys
+        self._agent_id = agent_id
+        self._token = token
+        self._socket_factory = socket_factory
+        self._socket: CanvasRelaySocket | None = None
+
+    async def connect(self) -> None:
+        headers = canvas_relay_upgrade_headers(self._keys)
+        url = canvas_relay_websocket_url(self._relay_url, agent_id=self._agent_id, token=self._token)
+        if self._socket_factory is None:
+            raise ImportError(
+                "canvas relay WebSocket requires an injected socket_factory; "
+                "beeos-cloud-harness-sdk does not depend on websockets"
+            )
+        socket = self._socket_factory(url, headers)
+        self._socket = socket
+        await socket.wait_open()
+
+    def join(self, canvas_id: str) -> None:
+        self._send(canvas_relay_join_frame(canvas_id))
+
+    def leave(self, canvas_id: str) -> None:
+        self._send(canvas_relay_leave_frame(canvas_id))
+
+    def send_binary(self, canvas_id: str, payload: bytes) -> None:
+        self._send(encode_canvas_relay_binary(canvas_id, payload))
+
+    def close(self) -> None:
+        if self._socket is not None:
+            self._socket.close()
+            self._socket = None
+
+    def _send(self, data: str | bytes) -> None:
+        if self._socket is None:
+            raise RuntimeError("canvas relay is not connected")
+        self._socket.send(data)

beeos_cloud_harness_sdk/claims.py

@@ -0,0 +1,74 @@
+"""Invocation claim lifecycle. Message Service does not register these routes yet.
+
+Mirror of ``src/runtime-claim.ts``. Paths are the beeos-types contracts.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from beeos_cloud_harness_sdk.lease_http import CloudMessageRoutes, RuntimeLeaseCredential, RuntimeLeaseHttp
+from beeos_cloud_harness_sdk.runtime_plane import HarnessProtocolError
+
+_NEXT = frozenset({"claimed", "empty", "fenced"})
+_EXACT = frozenset({"claimed", "already_claimed", "fenced", "epoch_handoff_required", "terminal"})
+_RENEW = frozenset({"renewed", "fenced", "expired", "terminal"})
+
+
+async def _read_status(response: httpx.Response, what: str) -> dict[str, Any]:
+    text = response.text
+    if response.status_code >= 400:
+        raise HarnessProtocolError(f"{what} failed ({response.status_code})", response.status_code, text)
+    try:
+        body = response.json()
+    except ValueError as exc:
+        raise HarnessProtocolError(f"{what} returned an invalid result") from exc
+    if not isinstance(body, dict) or not isinstance(body.get("status"), str):
+        raise HarnessProtocolError(f"{what} returned an invalid result")
+    return body
+
+
+class RuntimeClaimClient:
+    def __init__(self, http: RuntimeLeaseHttp) -> None:
+        self._http = http
+
+    async def claim_next(self, credential: RuntimeLeaseCredential, body: dict[str, Any]) -> dict[str, Any]:
+        result = await _read_status(
+            await self._http.fetch("POST", CloudMessageRoutes.claim_next, credential, json_body=body),
+            "claim next",
+        )
+        if result["status"] not in _NEXT:
+            raise HarnessProtocolError("claim next returned an invalid status")
+        return result
+
+    async def claim_exact(self, credential: RuntimeLeaseCredential, body: dict[str, Any]) -> dict[str, Any]:
+        result = await _read_status(
+            await self._http.fetch(
+                "POST", CloudMessageRoutes.claim_exact(str(body["operationId"])), credential, json_body=body,
+            ),
+            "claim exact",
+        )
+        if result["status"] not in _EXACT:
+            raise HarnessProtocolError("claim exact returned an invalid status")
+        return result
+
+    async def renew_claim(self, credential: RuntimeLeaseCredential, body: dict[str, Any]) -> dict[str, Any]:
+        result = await _read_status(
+            await self._http.fetch(
+                "POST", CloudMessageRoutes.claim_renew(str(body["operationId"])), credential, json_body=body,
+            ),
+            "claim renew",
+        )
+        if result["status"] not in _RENEW:
+            raise HarnessProtocolError("claim renew returned an invalid status")
+        return result
+
+    async def release_claim(self, credential: RuntimeLeaseCredential, body: dict[str, Any]) -> None:
+        response = await self._http.fetch(
+            "POST", CloudMessageRoutes.claim_release(str(body["operationId"])), credential, json_body=body,
+        )
+        if response.status_code != 204:
+            raise HarnessProtocolError(
+                f"claim release failed ({response.status_code})", response.status_code, response.text,
+            )