brickly-sdk 0.1.0__py3-none-any.whl

brickly/__init__.py

@@ -0,0 +1,31 @@
+from .api import (
+    BricklyRuntime,
+    CommandContext,
+    EventEnvelope,
+    EventsApi,
+    UiApi,
+    WebContentsApi,
+    WindowHandle,
+)
+from .errors import BppError, payload_to_error
+from .protocol import PROTOCOL_VERSION, PlatformSystemPathName
+from .runtime import BppTransport
+from .system import ClipboardApi, PlatformApi, SystemApi
+
+__all__ = [
+    "BppError",
+    "BppTransport",
+    "BricklyRuntime",
+    "ClipboardApi",
+    "CommandContext",
+    "EventEnvelope",
+    "EventsApi",
+    "PlatformApi",
+    "PROTOCOL_VERSION",
+    "PlatformSystemPathName",
+    "SystemApi",
+    "UiApi",
+    "WebContentsApi",
+    "WindowHandle",
+    "payload_to_error",
+]

brickly/api.py

@@ -0,0 +1,601 @@
+from __future__ import annotations
+
+import sys
+import threading
+import time
+from contextvars import ContextVar
+from collections import defaultdict
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, DefaultDict, Dict, Iterator, List, Optional
+
+from .errors import BppError
+from .protocol import PROTOCOL_VERSION, BrickUiWindowOptions, InvokeStreamEvent
+from .runtime import BppTransport
+from .system import PlatformApi, SystemApi
+
+CommandHandler = Callable[["CommandContext", Any], Any]
+EventHandler = Callable[[Any, Dict[str, Any]], None]
+_current_request_id: ContextVar[Optional[str]] = ContextVar("brickly_current_request_id", default=None)
+
+
+def _current_parent_request_id() -> Optional[str]:
+    return _current_request_id.get()
+
+
+def _require_parent_request_id(operation: str) -> str:
+    parent_request_id = _current_parent_request_id()
+    if not parent_request_id:
+        raise BppError(
+            "PARENT_INVOCATION_REQUIRED",
+            f"{operation} must run inside command handler; use invoke_root() for root calls",
+        )
+    return parent_request_id
+
+
+def _explicit_payload_request_id(args: List[Any]) -> Optional[str]:
+    if len(args) < 2 or not isinstance(args[1], dict):
+        return None
+    request_id = args[1].get("requestId")
+    return request_id if isinstance(request_id, str) and request_id else None
+
+
+@dataclass(frozen=True)
+class EventEnvelope:
+    event: str
+    payload: Any
+    source_brick_id: str
+    published_at: float
+
+
+class CommandContext:
+    def __init__(self, runtime: "BricklyRuntime", request_id: str, command_id: str) -> None:
+        self.request_id = request_id
+        self.command_id = command_id
+        self._runtime = runtime
+        self._cancel_event = threading.Event()
+
+    @property
+    def ui(self) -> "UiApi":
+        return self._runtime.ui
+
+    @property
+    def events(self) -> "EventsApi":
+        return self._runtime.events
+
+    @property
+    def platform(self) -> PlatformApi:
+        return self._runtime.platform
+
+    @property
+    def system(self) -> SystemApi:
+        return self._runtime.system
+
+    @property
+    def config(self) -> Dict[str, Any]:
+        return self._runtime.config
+
+    @property
+    def cancel_event(self) -> threading.Event:
+        return self._cancel_event
+
+    def is_cancelled(self) -> bool:
+        return self._cancel_event.is_set()
+
+    def on_cancel(self, handler: Callable[[], None]) -> None:
+        self._runtime._set_cancel_handler(self.request_id, handler)
+        if self.is_cancelled():
+            handler()
+
+    def progress(self, value: float, message: Optional[str] = None) -> None:
+        payload: Dict[str, Any] = {"type": "command.progress", "id": self.request_id, "progress": value}
+        if message:
+            payload["message"] = message
+        self._runtime.transport.send(payload)
+
+    def chunk(self, chunk: Any, name: Optional[str] = None) -> None:
+        payload: Dict[str, Any] = {"type": "command.chunk", "id": self.request_id, "chunk": chunk}
+        if name:
+            payload["name"] = name
+        self._runtime.transport.send(payload)
+
+    def output(self, name: str, value: Any) -> None:
+        self._runtime.transport.send({"type": "command.output", "id": self.request_id, "name": name, "value": value})
+
+    def invoke(
+        self,
+        brick_id: str,
+        command_id: str,
+        input_value: Any = None,
+        profile_id: Optional[str] = None,
+    ) -> Any:
+        return self._runtime.invoke(brick_id, command_id, input_value, profile_id)
+
+    def invoke_stream(
+        self,
+        brick_id: str,
+        command_id: str,
+        input_value: Any = None,
+        profile_id: Optional[str] = None,
+    ) -> Iterator[InvokeStreamEvent]:
+        return self._runtime.invoke_stream(brick_id, command_id, input_value, profile_id)
+
+    def open_session(
+        self,
+        brick_id: str,
+        profile_id: Optional[str] = None,
+    ) -> "BrickSession":
+        return self._runtime.open_session(brick_id, profile_id)
+
+    def _cancel(self) -> None:
+        self._cancel_event.set()
+
+
+class WebContentsApi:
+    def __init__(self, window: "WindowHandle") -> None:
+        self._window = window
+
+    def send(self, channel: str, *args: Any) -> None:
+        self._window.call("webContents.send", [channel, *args])
+
+    def execute_javascript(self, code: str, user_gesture: Optional[bool] = None) -> Any:
+        args: List[Any] = [code] if user_gesture is None else [code, user_gesture]
+        return self._window.call("webContents.executeJavaScript", args)
+
+    def open_dev_tools(self, options: Optional[Dict[str, Any]] = None) -> None:
+        self._window.call("webContents.openDevTools", [] if options is None else [options])
+
+    def close_dev_tools(self) -> None:
+        self._window.call("webContents.closeDevTools")
+
+    def toggle_dev_tools(self) -> None:
+        self._window.call("webContents.toggleDevTools")
+
+    def is_dev_tools_opened(self) -> bool:
+        return bool(self._window.call("webContents.isDevToolsOpened"))
+
+    def get_url(self) -> str:
+        return str(self._window.call("webContents.getURL"))
+
+    def get_title(self) -> str:
+        return str(self._window.call("webContents.getTitle"))
+
+
+class WindowHandle:
+    def __init__(self, runtime: "BricklyRuntime", window_id: int) -> None:
+        self._runtime = runtime
+        self.id = window_id
+        self.closed = False
+        self._listeners: DefaultDict[str, List[Callable[[Any], None]]] = defaultdict(list)
+        self.web_contents = WebContentsApi(self)
+
+    def on(self, event: str, handler: Callable[[Any], None]) -> Callable[[], None]:
+        self._listeners[event].append(handler)
+
+        def off() -> None:
+            try:
+                self._listeners[event].remove(handler)
+            except ValueError:
+                pass
+
+        return off
+
+    def call(self, method: str, args: Optional[List[Any]] = None) -> Any:
+        if self.closed and method != "isDestroyed":
+            raise BppError("INVALID_INPUT", f"Window {self.id} already closed")
+        payload: Dict[str, Any] = {"type": "host.ui.callWindow", "windowId": self.id, "method": method, "args": args or []}
+        parent_request_id = _current_parent_request_id()
+        if method == "webContents.send" and not parent_request_id:
+            parent_request_id = _explicit_payload_request_id(args or [])
+        if method == "webContents.send" and not parent_request_id:
+            raise BppError(
+                "PARENT_INVOCATION_REQUIRED",
+                "web_contents.send() must run inside command handler or include payload.requestId",
+            )
+        if method == "webContents.send":
+            payload["parentRequestId"] = parent_request_id
+        return self._runtime.transport.host_call(
+            payload
+        )
+
+    def close(self) -> None:
+        if self.closed:
+            return
+        self.closed = True
+        self._runtime.transport.host_call({"type": "host.ui.closeWindow", "windowId": self.id})
+
+    def emit(self, event: str, payload: Any) -> None:
+        if event == "closed":
+            self.closed = True
+            self._runtime._windows.pop(self.id, None)
+        for handler in list(self._listeners.get(event, [])):
+            handler(payload)
+
+    def set_bounds(self, bounds: Dict[str, Any]) -> None:
+        self.call("setBounds", [bounds])
+
+    def get_bounds(self) -> Any:
+        return self.call("getBounds")
+
+    def set_position(self, x: int, y: int) -> None:
+        self.call("setPosition", [x, y])
+
+    def get_position(self) -> Any:
+        return self.call("getPosition")
+
+    def set_size(self, width: int, height: int) -> None:
+        self.call("setSize", [width, height])
+
+    def get_size(self) -> Any:
+        return self.call("getSize")
+
+    def set_opacity(self, opacity: float) -> None:
+        self.call("setOpacity", [opacity])
+
+    def get_opacity(self) -> float:
+        return float(self.call("getOpacity"))
+
+    def set_always_on_top(self, flag: bool, level: Optional[str] = None) -> None:
+        self.call("setAlwaysOnTop", [flag] if level is None else [flag, level])
+
+    def set_ignore_mouse_events(self, ignore: bool, options: Optional[Dict[str, Any]] = None) -> None:
+        self.call("setIgnoreMouseEvents", [ignore] if options is None else [ignore, options])
+
+    def minimize(self) -> None:
+        self.call("minimize")
+
+    def maximize(self) -> None:
+        self.call("maximize")
+
+    def restore(self) -> None:
+        self.call("restore")
+
+    def hide(self) -> None:
+        self.call("hide")
+
+    def show(self) -> None:
+        self.call("show")
+
+    def focus(self) -> None:
+        self.call("focus")
+
+    def load_url(self, url: str, options: Optional[Dict[str, Any]] = None) -> None:
+        self.call("loadURL", [url] if options is None else [url, options])
+
+    def load_file(self, file_path: str, options: Optional[Dict[str, Any]] = None) -> None:
+        self.call("loadFile", [file_path] if options is None else [file_path, options])
+
+    def reload(self) -> None:
+        self.call("reload")
+
+    def is_destroyed(self) -> bool:
+        return bool(self.call("isDestroyed"))
+
+
+class UiApi:
+    def __init__(self, runtime: "BricklyRuntime") -> None:
+        self._runtime = runtime
+
+    def create_browser_window(self, url: str, options: Optional[BrickUiWindowOptions] = None) -> WindowHandle:
+        result = self._runtime.transport.host_call(
+            {"type": "host.ui.createBrowserWindow", "url": url, "options": options or {}}
+        )
+        window_id = int(result.get("windowId")) if isinstance(result, dict) else int(result)
+        handle = WindowHandle(self._runtime, window_id)
+        self._runtime._windows[window_id] = handle
+        return handle
+
+    def list_windows(self) -> Any:
+        return self._runtime.transport.host_call({"type": "host.ui.listWindows"})
+
+
+class EventsApi:
+    def __init__(self, runtime: "BricklyRuntime") -> None:
+        self._runtime = runtime
+
+    def on(self, event: str, handler: EventHandler) -> Callable[[], None]:
+        self._runtime._event_listeners[event].append(handler)
+
+        def off() -> None:
+            try:
+                self._runtime._event_listeners[event].remove(handler)
+            except ValueError:
+                pass
+
+        return off
+
+    def publish(self, event: str, payload: Optional[Any] = None) -> None:
+        message: Dict[str, Any] = {"type": "host.event.publish", "event": event}
+        if payload is not None:
+            message["payload"] = payload
+        self._runtime.transport.host_call(message)
+
+
+class BrickSession:
+    def __init__(
+        self,
+        runtime: "BricklyRuntime",
+        session_id: str,
+        brick_id: str,
+        profile_id: Optional[str] = None,
+    ) -> None:
+        self._runtime = runtime
+        self.id = session_id
+        self.brick_id = brick_id
+        self.profile_id = profile_id
+
+    def invoke(self, command_id: str, input_value: Any = None) -> Any:
+        parent_request_id = _require_parent_request_id("session.invoke()")
+        return self._runtime.transport.host_call(
+            {
+                "type": "host.session.invoke",
+                "sessionId": self.id,
+                "commandId": command_id,
+                "input": input_value,
+                "parentRequestId": parent_request_id,
+            }
+        )
+
+    def close(self) -> None:
+        self._runtime.transport.host_call({"type": "host.session.close", "sessionId": self.id})
+
+
+class BricklyRuntime:
+    def __init__(
+        self,
+        brick_id: str,
+        protocol_version: str = PROTOCOL_VERSION,
+        transport: Optional[BppTransport] = None,
+    ) -> None:
+        self.brick_id = brick_id
+        self.protocol_version = protocol_version
+        self.transport = transport or BppTransport(brick_id)
+        self.ui = UiApi(self)
+        self.events = EventsApi(self)
+        self.platform = PlatformApi(self)
+        self.system = self.platform.system
+        self.config: Dict[str, Any] = {}
+        self._command_handlers: Dict[str, CommandHandler] = {}
+        self._cancel_handlers: Dict[str, Callable[[], None]] = {}
+        self._contexts: Dict[str, CommandContext] = {}
+        self._event_listeners: DefaultDict[str, List[EventHandler]] = defaultdict(list)
+        self._windows: Dict[int, WindowHandle] = {}
+        self._ready_handler: Optional[Callable[[], Any]] = None
+        self._shutdown_handler: Optional[Callable[[], Any]] = None
+        self._started = False
+        self._done = threading.Event()
+        self.transport.on("command", self._handle_command)
+        self.transport.on("event", self._handle_event)
+        self.transport.on("message", self._handle_message)
+        self.transport.on("shutdown", self._handle_shutdown)
+        self.transport.on("end", self._done.set)
+        self.transport.on("error", lambda error: self.transport.log("transport error:", repr(error)))
+
+    def on_command(self, command_id: str, handler: Optional[CommandHandler] = None):
+        def decorator(fn: CommandHandler) -> CommandHandler:
+            self._command_handlers[command_id] = fn
+            return fn
+
+        if handler is not None:
+            return decorator(handler)
+        return decorator
+
+    def on_ready(self, handler: Callable[[], Any]) -> Callable[[], Any]:
+        self._ready_handler = handler
+        return handler
+
+    def on_shutdown(self, handler: Callable[[], Any]) -> Callable[[], Any]:
+        self._shutdown_handler = handler
+        return handler
+
+    def start(self, block: bool = True) -> "BricklyRuntime":
+        if self._started:
+            return self
+        self._started = True
+        self.transport.start()
+        if block:
+            self._done.wait()
+        return self
+
+    run = start
+
+    def stop(self) -> None:
+        self.transport.stop("brick stopped")
+        self._done.set()
+
+    def log(self, *parts: Any) -> None:
+        self.transport.log(*parts)
+
+    def invoke(
+        self,
+        brick_id: str,
+        command_id: str,
+        input_value: Any = None,
+        profile_id: Optional[str] = None,
+    ) -> Any:
+        parent_request_id = _require_parent_request_id("invoke()")
+        message: Dict[str, Any] = {
+            "type": "host.invoke",
+            "brickId": brick_id,
+            "commandId": command_id,
+            "input": input_value,
+            "parentRequestId": parent_request_id,
+        }
+        if profile_id:
+            message["profileId"] = profile_id
+        return self.transport.host_call(message)
+
+    def invoke_root(
+        self,
+        brick_id: str,
+        command_id: str,
+        input_value: Any = None,
+        profile_id: Optional[str] = None,
+    ) -> Any:
+        message: Dict[str, Any] = {
+            "type": "host.invokeRoot",
+            "brickId": brick_id,
+            "commandId": command_id,
+            "input": input_value,
+        }
+        if profile_id:
+            message["profileId"] = profile_id
+        return self.transport.host_call(message)
+
+    def invoke_stream(
+        self,
+        brick_id: str,
+        command_id: str,
+        input_value: Any = None,
+        profile_id: Optional[str] = None,
+    ) -> Iterator[InvokeStreamEvent]:
+        def stream() -> Iterator[InvokeStreamEvent]:
+            parent_request_id = _require_parent_request_id("invoke_stream()")
+            message: Dict[str, Any] = {
+                "type": "host.invoke",
+                "brickId": brick_id,
+                "commandId": command_id,
+                "input": input_value,
+                "stream": True,
+                "parentRequestId": parent_request_id,
+            }
+            if profile_id:
+                message["profileId"] = profile_id
+            yield from self.transport.host_call_stream(message)
+
+        return stream()
+
+    def open_session(
+        self,
+        brick_id: str,
+        profile_id: Optional[str] = None,
+    ) -> BrickSession:
+        message: Dict[str, Any] = {"type": "host.session.open", "brickId": brick_id}
+        if profile_id:
+            message["profileId"] = profile_id
+        result = self.transport.host_call(message)
+        if not isinstance(result, dict):
+            raise BppError("PROTOCOL_ERROR", "host.session.open returned invalid result")
+        return BrickSession(
+            self,
+            str(result.get("sessionId") or ""),
+            str(result.get("brickId") or brick_id),
+            str(result["profileId"]) if result.get("profileId") else None,
+        )
+
+    def _handle_message(self, message: Dict[str, Any]) -> None:
+        if message.get("type") != "host.hello":
+            return
+        config = message.get("config")
+        self.config = config if isinstance(config, dict) else {}
+        self.transport.send(
+            {"type": "runtime.ready", "protocolVersion": self.protocol_version, "brickId": self.brick_id}
+        )
+        if self._ready_handler:
+            threading.Thread(target=self._run_ready, name="brickly-ready", daemon=True).start()
+
+    def _run_ready(self) -> None:
+        try:
+            assert self._ready_handler is not None
+            self._ready_handler()
+        except BaseException as error:  # noqa: BLE001
+            self.transport.log("on_ready error:", BppError.from_exception(error).message)
+
+    def _handle_command(self, message: Dict[str, Any]) -> None:
+        msg_type = message.get("type")
+        if msg_type == "command.cancel":
+            req_id = str(message.get("id") or "")
+            ctx = self._contexts.get(req_id)
+            if ctx:
+                ctx._cancel()
+            handler = self._cancel_handlers.get(req_id)
+            if handler:
+                try:
+                    handler()
+                except BaseException as error:  # noqa: BLE001
+                    self.transport.log("cancel handler error:", repr(error))
+            return
+        if msg_type != "command.invoke":
+            return
+        req_id = str(message.get("id") or "")
+        command_id = str(message.get("commandId") or "")
+        handler = self._command_handlers.get(command_id)
+        if handler is None:
+            self.transport.send(
+                {
+                    "type": "command.error",
+                    "id": req_id,
+                    "error": {"code": "COMMAND_NOT_FOUND", "message": f"Unknown command: {command_id}"},
+                }
+            )
+            return
+        ctx = CommandContext(self, req_id, command_id)
+        self._contexts[req_id] = ctx
+        thread = threading.Thread(
+            target=self._run_command,
+            args=(handler, ctx, message.get("input")),
+            name=f"brickly-command-{command_id}",
+            daemon=True,
+        )
+        thread.start()
+
+    def _run_command(self, handler: CommandHandler, ctx: CommandContext, input_value: Any) -> None:
+        token = _current_request_id.set(ctx.request_id)
+        try:
+            result = handler(ctx, input_value)
+            self.transport.send({"type": "command.result", "id": ctx.request_id, "result": result})
+        except BaseException as error:  # noqa: BLE001
+            self.transport.send(
+                {"type": "command.error", "id": ctx.request_id, "error": BppError.from_exception(error).to_json()}
+            )
+        finally:
+            _current_request_id.reset(token)
+            self._contexts.pop(ctx.request_id, None)
+            self._cancel_handlers.pop(ctx.request_id, None)
+
+    def _handle_event(self, message: Dict[str, Any]) -> None:
+        event = str(message.get("event") or "")
+        payload = message.get("payload")
+        if event.startswith("window.") and isinstance(payload, dict):
+            window_id = payload.get("windowId")
+            if isinstance(window_id, (int, float)):
+                handle = self._windows.get(int(window_id))
+                if handle:
+                    handle.emit(event.removeprefix("window."), payload)
+
+        envelope = {
+            "event": event,
+            "payload": payload,
+            "sourceBrickId": message.get("sourceBrickId", ""),
+            "publishedAt": message.get("publishedAt", 0),
+        }
+        for handler in list(self._event_listeners.get(event, [])):
+            threading.Thread(
+                target=self._run_event_handler,
+                args=(handler, payload, envelope),
+                name=f"brickly-event-{event}",
+                daemon=True,
+            ).start()
+
+    def _handle_shutdown(self) -> None:
+        threading.Thread(target=self._run_shutdown, name="brickly-shutdown", daemon=True).start()
+
+    def _run_event_handler(self, handler: EventHandler, payload: Any, envelope: Dict[str, Any]) -> None:
+        try:
+            handler(payload, envelope)
+        except BaseException as error:  # noqa: BLE001
+            self.transport.log("event handler error:", repr(error))
+
+    def _run_shutdown(self) -> None:
+        try:
+            if self._shutdown_handler:
+                self._shutdown_handler()
+        except BaseException as error:  # noqa: BLE001
+            self.transport.log("shutdown handler error:", repr(error))
+        self.transport.send({"type": "runtime.bye"})
+        time.sleep(0.05)
+        self._done.set()
+        sys.exit(0)
+
+    def _set_cancel_handler(self, req_id: str, handler: Callable[[], None]) -> None:
+        self._cancel_handlers[req_id] = handler

brickly/errors.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class BppError(Exception):
+    """SDK error type that serializes directly to BPP error payloads."""
+
+    def __init__(self, code: str, message: str, details: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details
+
+    def to_json(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"code": self.code, "message": self.message}
+        if self.details is not None:
+            payload["details"] = self.details
+        return payload
+
+    @classmethod
+    def from_exception(cls, error: BaseException) -> "BppError":
+        if isinstance(error, BppError):
+            return error
+        return cls("INTERNAL_ERROR", str(error) or error.__class__.__name__)
+
+
+def payload_to_error(payload: Optional[Dict[str, Any]]) -> BppError:
+    if not payload:
+        return BppError("INTERNAL_ERROR", "Unknown BPP error")
+    return BppError(
+        str(payload.get("code") or "INTERNAL_ERROR"),
+        str(payload.get("message") or "Unknown BPP error"),
+        payload.get("details"),
+    )
+

brickly/protocol.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Literal, TypedDict
+
+PROTOCOL_VERSION = "0.1.0"
+
+BridgeErrorCode = str
+
+
+class BridgeErrorPayload(TypedDict, total=False):
+    code: BridgeErrorCode
+    message: str
+    details: Any
+
+
+BppMessage = Dict[str, Any]
+BrickUiWindowOptions = Dict[str, Any]
+BrickWindowMethod = str
+ClipboardContent = Any
+ClipboardReadResult = Dict[str, Any]
+ClipboardSetResult = Dict[str, Any]
+HostResourceRegisterPayload = Dict[str, Any]
+EventName = str
+InvokeStreamEvent = Dict[str, Any]
+CommandMessageType = Literal["command.invoke", "command.cancel"]
+PlatformSystemPathName = Literal[
+    "home",
+    "appData",
+    "assets",
+    "userData",
+    "sessionData",
+    "temp",
+    "exe",
+    "module",
+    "desktop",
+    "documents",
+    "downloads",
+    "music",
+    "pictures",
+    "videos",
+    "recent",
+    "logs",
+    "crashDumps",
+]

brickly/runtime.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import io
+import itertools
+import json
+import os
+import queue
+import sys
+import threading
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any, DefaultDict, Dict, Iterator, List, Optional, TextIO, Tuple
+
+from .errors import BppError, payload_to_error
+
+
+MessageHandler = Callable[[Dict[str, Any]], None]
+VoidHandler = Callable[[], None]
+ErrorHandler = Callable[[BaseException], None]
+DEFAULT_HOST_CALL_TIMEOUT_SECONDS = 10.0
+
+
+def _ensure_utf8_stdio() -> None:
+    """Re-open stdout/stderr with UTF-8 encoding so Chinese text survives pipe transport on Windows.
+
+    Uses surrogatepass so lone surrogates (from malformed data) are encoded into their
+    well-defined UTF-8 byte sequences instead of crashing the write.  V8's UTF-8 decoder
+    handles these gracefully, and JavaScript strings natively support lone surrogates."""
+    for attr in ('stdout', 'stderr'):
+        stream = getattr(sys, attr)
+        if (
+            hasattr(stream, 'buffer')
+            and hasattr(stream, 'encoding')
+            and stream.encoding is not None
+            and stream.encoding.lower() != 'utf-8'
+        ):
+            try:
+                setattr(
+                    sys,
+                    attr,
+                    io.TextIOWrapper(stream.buffer, encoding='utf-8', errors='surrogatepass'),
+                )
+            except Exception:
+                pass
+
+
+_ensure_utf8_stdio()
+
+
+class BppTransport:
+    """NDJSON-over-stdio transport for Brickly brick runtimes."""
+
+    def __init__(
+        self,
+        brick_id: str,
+        stdin: Optional[TextIO] = None,
+        stdout: Optional[TextIO] = None,
+        stderr: Optional[TextIO] = None,
+    ) -> None:
+        self.brick_id = brick_id
+        self.stdin = stdin or sys.stdin
+        self.stdout = stdout or sys.stdout
+        self.stderr = stderr or sys.stderr
+        self._id_counter = itertools.count(1)
+        self._stdout_lock = threading.Lock()
+        self._pending: Dict[str, queue.Queue[Tuple[bool, Any]]] = {}
+        self._stream_pending: Dict[str, queue.Queue[Tuple[str, Any]]] = {}
+        self._pending_lock = threading.Lock()
+        self._handlers: DefaultDict[str, List[Callable[..., None]]] = defaultdict(list)
+        self._started = False
+        self._stop_event = threading.Event()
+        self._reader_thread: Optional[threading.Thread] = None
+
+    def on(self, event: str, handler: Callable[..., None]) -> None:
+        self._handlers[event].append(handler)
+
+    def emit(self, event: str, *args: Any) -> None:
+        for handler in list(self._handlers.get(event, [])):
+            try:
+                handler(*args)
+            except BaseException as error:  # noqa: BLE001
+                self.log("handler error:", repr(error))
+
+    def start(self) -> None:
+        if self._started:
+            return
+        self._started = True
+        self._reader_thread = threading.Thread(target=self._read_loop, name="brickly-bpp-reader", daemon=True)
+        self._reader_thread.start()
+
+    def stop(self, reason: str = "transport stopped") -> None:
+        if not self._started:
+            return
+        self._started = False
+        self._stop_event.set()
+        with self._pending_lock:
+            pending = list(self._pending.values())
+            self._pending.clear()
+            stream_pending = list(self._stream_pending.values())
+            self._stream_pending.clear()
+        error = BppError("PROCESS_EXITED", reason)
+        for waiter in pending:
+            waiter.put((False, error))
+        for waiter in stream_pending:
+            waiter.put(("error", error))
+
+    def wait(self) -> None:
+        if self._reader_thread:
+            self._reader_thread.join()
+
+    def send(self, message: Dict[str, Any]) -> None:
+        line = json.dumps(message, ensure_ascii=False, default=str) + "\n"
+        with self._stdout_lock:
+            self.stdout.write(line)
+            self.stdout.flush()
+
+    def log(self, *parts: Any) -> None:
+        rendered = " ".join(part if isinstance(part, str) else json.dumps(part, ensure_ascii=False, default=str) for part in parts)
+        self.stderr.write(f"{rendered}\n")
+        self.stderr.flush()
+
+    def host_call(self, message: Dict[str, Any], timeout: Optional[float] = DEFAULT_HOST_CALL_TIMEOUT_SECONDS) -> Any:
+        req_id = self._next_id()
+        waiter: queue.Queue[Tuple[bool, Any]] = queue.Queue(maxsize=1)
+        with self._pending_lock:
+            self._pending[req_id] = waiter
+        self.send({**message, "id": req_id})
+        try:
+            ok, value = waiter.get(timeout=timeout)
+        except queue.Empty as exc:
+            with self._pending_lock:
+                self._pending.pop(req_id, None)
+            raise BppError("TIMEOUT", f"Timed out waiting for host response: {message.get('type')}") from exc
+        if ok:
+            return value
+        raise value
+
+    def host_call_stream(
+        self,
+        message: Dict[str, Any],
+        timeout: Optional[float] = DEFAULT_HOST_CALL_TIMEOUT_SECONDS,
+    ) -> Iterator[Dict[str, Any]]:
+        req_id = self._next_id()
+        waiter: queue.Queue[Tuple[str, Any]] = queue.Queue()
+        with self._pending_lock:
+            self._stream_pending[req_id] = waiter
+        self.send({**message, "id": req_id})
+        try:
+            while True:
+                try:
+                    kind, value = waiter.get(timeout=timeout)
+                except queue.Empty as exc:
+                    with self._pending_lock:
+                        self._stream_pending.pop(req_id, None)
+                    raise BppError("TIMEOUT", f"Timed out waiting for host response: {message.get('type')}") from exc
+                if kind == "error":
+                    raise value
+                yield value
+                if kind == "result":
+                    break
+        finally:
+            with self._pending_lock:
+                self._stream_pending.pop(req_id, None)
+
+    def _next_id(self) -> str:
+        return f"{self.brick_id}-{os.getpid()}-{next(self._id_counter)}"
+
+    def _read_loop(self) -> None:
+        try:
+            for raw in self.stdin:
+                if self._stop_event.is_set():
+                    break
+                line = raw.strip()
+                if not line:
+                    continue
+                try:
+                    message = json.loads(line)
+                except json.JSONDecodeError as exc:
+                    self.emit("error", BppError("PROTOCOL_ERROR", f"Invalid JSON line: {exc}"))
+                    continue
+                if isinstance(message, dict):
+                    self._dispatch(message)
+        finally:
+            self.emit("end")
+
+    def _dispatch(self, message: Dict[str, Any]) -> None:
+        msg_type = message.get("type")
+        if msg_type in ("host.invoke.progress", "host.invoke.chunk", "host.invoke.output"):
+            self._resolve_stream_event(str(message.get("id", "")), message)
+            return
+        if msg_type == "host.result":
+            if self._resolve_stream_result(str(message.get("id", "")), True, message.get("result")):
+                return
+            self._resolve_pending(str(message.get("id", "")), True, message.get("result"))
+            return
+        if msg_type == "host.error":
+            if self._resolve_stream_result(
+                str(message.get("id", "")),
+                False,
+                payload_to_error(message.get("error")),
+            ):
+                return
+            self._resolve_pending(str(message.get("id", "")), False, payload_to_error(message.get("error")))
+            return
+        if msg_type == "runtime.ping":
+            self.send({"type": "runtime.pong", "id": message.get("id", "")})
+            return
+        if msg_type == "runtime.shutdown":
+            self.emit("shutdown")
+            return
+        if msg_type == "event.notify":
+            self.emit("event", message)
+            self.emit("message", message)
+            return
+        if msg_type in ("command.invoke", "command.cancel"):
+            self.emit("command", message)
+            self.emit("message", message)
+            return
+        self.emit("message", message)
+
+    def _resolve_pending(self, req_id: str, ok: bool, value: Any) -> None:
+        with self._pending_lock:
+            waiter = self._pending.pop(req_id, None)
+        if waiter:
+            waiter.put((ok, value))
+
+    def _resolve_stream_event(self, req_id: str, message: Dict[str, Any]) -> None:
+        with self._pending_lock:
+            waiter = self._stream_pending.get(req_id)
+        if not waiter:
+            return
+        msg_type = message.get("type")
+        event_type = str(msg_type).removeprefix("host.invoke.")
+        event = {key: value for key, value in message.items() if key not in ("type", "id")}
+        event["type"] = event_type
+        waiter.put(("event", event))
+
+    def _resolve_stream_result(self, req_id: str, ok: bool, value: Any) -> bool:
+        with self._pending_lock:
+            waiter = self._stream_pending.get(req_id)
+        if not waiter:
+            return False
+        if ok:
+            waiter.put(("result", {"type": "result", "result": value}))
+        else:
+            waiter.put(("error", value))
+        return True

brickly/system.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from .protocol import ClipboardContent, ClipboardReadResult, ClipboardSetResult, PlatformSystemPathName
+
+if TYPE_CHECKING:
+    from .api import BricklyRuntime
+
+
+class PlatformApi:
+    def __init__(self, runtime: "BricklyRuntime") -> None:
+        self.system = SystemApi(runtime)
+        self.clipboard = ClipboardApi(runtime)
+
+
+class ClipboardApi:
+    def __init__(self, runtime: "BricklyRuntime") -> None:
+        self._runtime = runtime
+
+    def read_content(self) -> ClipboardReadResult:
+        return self._runtime.transport.host_call({"type": "host.platform.clipboard.readContent"})
+
+    def set_content(self, content: ClipboardContent) -> ClipboardSetResult:
+        return self._runtime.transport.host_call(
+            {"type": "host.platform.clipboard.setContent", "content": content}
+        )
+
+
+class SystemApi:
+    def __init__(self, runtime: "BricklyRuntime") -> None:
+        self._runtime = runtime
+
+    def show_notification(self, body: str, click_feature_code: Optional[str] = None) -> None:
+        message: dict[str, str] = {"type": "host.platform.system.showNotification", "body": body}
+        if click_feature_code:
+            message["clickFeatureCode"] = click_feature_code
+        self._runtime.transport.host_call(message)
+
+    def shell_open_path(self, full_path: str) -> None:
+        self._runtime.transport.host_call(
+            {"type": "host.platform.system.shellOpenPath", "fullPath": full_path}
+        )
+
+    def shell_trash_item(self, full_path: str) -> None:
+        self._runtime.transport.host_call(
+            {"type": "host.platform.system.shellTrashItem", "fullPath": full_path}
+        )
+
+    def shell_show_item_in_folder(self, full_path: str) -> None:
+        self._runtime.transport.host_call(
+            {"type": "host.platform.system.shellShowItemInFolder", "fullPath": full_path}
+        )
+
+    def shell_open_external(self, url: str) -> None:
+        self._runtime.transport.host_call({"type": "host.platform.system.shellOpenExternal", "url": url})
+
+    def shell_beep(self) -> None:
+        self._runtime.transport.host_call({"type": "host.platform.system.shellBeep"})
+
+    def get_native_id(self) -> str:
+        return self._string_call("host.platform.system.getNativeId")
+
+    def get_app_name(self) -> str:
+        return self._string_call("host.platform.system.getAppName")
+
+    def get_app_version(self) -> str:
+        return self._string_call("host.platform.system.getAppVersion")
+
+    def get_path(self, name: PlatformSystemPathName) -> str:
+        result = self._runtime.transport.host_call({"type": "host.platform.system.getPath", "name": name})
+        return "" if result is None else str(result)
+
+    def get_file_icon(self, file_path: str) -> str:
+        result = self._runtime.transport.host_call(
+            {"type": "host.platform.system.getFileIcon", "filePath": file_path}
+        )
+        return "" if result is None else str(result)
+
+    def read_current_folder_path(self) -> str:
+        return self._string_call("host.platform.system.readCurrentFolderPath")
+
+    def read_current_browser_url(self) -> str:
+        return self._string_call("host.platform.system.readCurrentBrowserUrl")
+
+    def is_dev(self) -> bool:
+        return bool(self._runtime.transport.host_call({"type": "host.platform.system.isDev"}))
+
+    def is_macos(self) -> bool:
+        return bool(self._runtime.transport.host_call({"type": "host.platform.system.isMacOS"}))
+
+    def is_windows(self) -> bool:
+        return bool(self._runtime.transport.host_call({"type": "host.platform.system.isWindows"}))
+
+    def is_linux(self) -> bool:
+        return bool(self._runtime.transport.host_call({"type": "host.platform.system.isLinux"}))
+
+    def _string_call(self, message_type: str) -> str:
+        result = self._runtime.transport.host_call({"type": message_type})
+        return "" if result is None else str(result)

brickly_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: brickly-sdk
+Version: 0.1.0
+Summary: Python SDK for Brickly brick runtimes.
+Author: Brickly
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# brickly-sdk-python
+
+Python SDK for Brickly brick runtimes. It speaks BPP over stdin/stdout and keeps stdout reserved for protocol messages.
+
+## Quick Start
+
+```python
+from brickly import BricklyRuntime
+
+brick = BricklyRuntime("com.example.python")
+
+
+@brick.on_command("hello")
+def hello(ctx, input):
+    ctx.progress(0.5, "working...")
+    ctx.chunk("hello\n")
+    return {"ok": True, "input": input}
+
+
+brick.run()
+```
+
+The SDK handles:
+
+- `host.hello` -> `runtime.ready`
+- `runtime.ping` -> `runtime.pong`
+- `command.invoke` dispatch
+- `command.cancel` via `ctx.cancel_event`, `ctx.is_cancelled()`, and `ctx.on_cancel(...)`
+- `command.progress`, `command.chunk`, and `command.output`
+- `host.*` request id allocation and `host.result` / `host.error` routing
+- `runtime.shutdown` -> optional shutdown hook -> `runtime.bye`
+- `ui.create_browser_window`, `WindowHandle.call(...)`, and event routing for `window.*`
+- `events.publish(...)` and `events.on(...)`
+- `brick.platform.system.*` / `ctx.platform.system.*`, plus `brick.system.*` / `ctx.system.*` aliases
+- `brick.invoke(...)` / `ctx.invoke(...)` for child cross-brick command calls inside command scope
+- `brick.invoke_root(...)` for root cross-brick command calls outside command scope
+- `brick.invoke_stream(...)` / `ctx.invoke_stream(...)` for streaming child cross-brick command calls
+- `brick.open_session(...)` / `ctx.open_session(...)` for stateful cross-brick sessions
+- `brick.platform.clipboard.read_content()` / `set_content(...)`
+
+## Logging
+
+`brick.log(...)` writes plain messages to stderr. Stdout is reserved for BPP protocol messages. The Brickly host log center attaches the brick id, source, stream, and scope metadata when collecting stderr, so brick code should not add a `[brickId]` prefix by itself.
+
+## Window Example
+
+```python
+from brickly import BricklyRuntime
+
+brick = BricklyRuntime("com.example.window")
+
+
+@brick.on_command("open")
+def open_window(ctx, input):
+    win = ctx.ui.create_browser_window("ui/index.html", {"width": 640, "height": 480})
+    win.on("closed", lambda payload: brick.log("closed", payload))
+    win.set_title("Hello from Python")
+    return {"windowId": win.id}
+
+
+brick.run()
+```
+
+## Cross-Brick Invoke
+
+Inside a command handler, use `ctx.invoke` to call another brick command. The SDK automatically sends the current `parentRequestId`, so the host attaches the child call to the same invocation graph. Brickly starts, reuses, and recycles the target brick instance automatically. Pass `profile_id` when the target brick should run with a specific Profile; omit it to use the target brick's default Profile.
+
+```python
+result = ctx.invoke(
+    "com.brickly.openai",
+    "chat",
+    {"prompt": "hello"},
+    profile_id="work",
+)
+```
+
+Use `invoke_stream` when the target command emits progress, chunks, or named outputs before its final result. The SDK sends `host.invoke` with `stream: true` and yields events in host order:
+
+```python
+for event in ctx.invoke_stream("com.brickly.openai", "chat", {"prompt": "hello"}):
+    if event["type"] == "progress":
+        ctx.progress(event.get("progress", 0), event.get("message"))
+    elif event["type"] == "chunk":
+        ctx.chunk(event.get("chunk"))
+    elif event["type"] == "output":
+        ctx.output(event["name"], event.get("value"))
+    elif event["type"] == "result":
+        return event["result"]
+```
+
+If the host returns `host.error`, `invoke_stream` raises `BppError`, matching normal `invoke` error handling.
+
+To create a top-level cross-brick call outside command scope, use the explicit root API:
+
+```python
+result = brick.invoke_root(
+    "com.brickly.openai",
+    "chat",
+    {"prompt": "hello"},
+    profile_id="work",
+)
+```
+
+The caller manifest must declare the target brick and allowed commands in `dependencies`:
+
+```json
+"dependencies": {
+  "com.brickly.openai": {
+    "commands": ["chat"]
+  }
+}
+```
+
+## Platform System API
+
+`brick.platform.system.*`, `brick.system.*`, `ctx.platform.system.*`, and `ctx.system.*` call host system capabilities through BPP `host.platform.system.*`:
+
+```python
+@brick.on_command("show-app-info")
+def show_app_info(ctx, _input):
+    return {
+        "appName": ctx.system.get_app_name(),
+        "appVersion": ctx.system.get_app_version(),
+        "userData": ctx.system.get_path("userData"),
+        "isMacOS": ctx.system.is_macos(),
+    }
+```
+
+Current methods are `show_notification`, `shell_open_path`, `shell_trash_item`, `shell_show_item_in_folder`, `shell_open_external`, `shell_beep`, `get_native_id`, `get_app_name`, `get_app_version`, `get_path`, `get_file_icon`, `read_current_folder_path`, `read_current_browser_url`, `is_dev`, `is_macos`, `is_windows`, and `is_linux`.
+
+`get_path()` supports `home`, `appData`, `assets`, `userData`, `sessionData`, `temp`, `exe`, `module`, `desktop`, `documents`, `downloads`, `music`, `pictures`, `videos`, `recent`, `logs`, and `crashDumps`. Runtime calls are still checked by manifest permissions on the host side: notifications require `os.notification`; Shell capabilities require `os.exec`; app info, paths, native ID, platform checks, and current folder path reads require `os.env`; file icons require `fs.read`. `read_current_folder_path()` works when Finder is frontmost on macOS or Explorer is frontmost on Windows; it raises `CURRENT_FOLDER_UNAVAILABLE` when no readable foreground file-manager folder is available. `read_current_browser_url()` is reserved and currently returns `UNSUPPORTED_PLATFORM`.
+
+## Platform Clipboard API
+
+`brick.platform.clipboard.*` and `ctx.platform.clipboard.*` call host clipboard capabilities through BPP `host.platform.clipboard.*`:
+
+```python
+@brick.on_command("replace-clipboard")
+def replace_clipboard(ctx, _input):
+    previous = ctx.platform.clipboard.read_content()
+    updated = ctx.platform.clipboard.set_content({"kind": "text", "text": "Updated by Python"})
+    return {"previous": previous, "updated": updated}
+```
+
+Current methods are `read_content()` and `set_content(content)`.
+
+## Cross-Brick Sessions
+
+Use `ctx.open_session` when the target brick keeps in-memory state that must survive across multiple command calls. Calls through the same session are routed to the same target brick instance, and each `session.invoke` automatically carries the current `parentRequestId`, until `close()` is called or the caller brick instance exits.
+
+```python
+session = ctx.open_session("com.brickly.openai", profile_id="work")
+
+try:
+    session.invoke("start-thread", {"title": "Draft"})
+    reply = session.invoke("chat", {"prompt": "continue the thread"})
+finally:
+    session.close()
+```
+
+`profile_id` is the target brick Profile ID. Session invokes are checked against the caller manifest's `dependencies[target].commands` on every command call.
+
+## Errors
+
+Raise `BppError` to preserve a specific Brickly error code:
+
+```python
+from brickly import BppError
+
+raise BppError("INVALID_INPUT", "url is required")
+```

brickly_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+brickly/__init__.py,sha256=S3ouUBU8SRYpcPwDCKZ2JUeCNvNl1Qf4S-tmUa7x9PE,667
+brickly/api.py,sha256=i2YmfwmqPHAPFtE9DC5khxbbavEI5QpGP1h_bf-jYHk,21380
+brickly/errors.py,sha256=tHgmiCYX4JpYGKb6bXzlhTxAyZN8Z-GxzB_upVF9gBo,1167
+brickly/protocol.py,sha256=-hnB5mbh7vXW3Z_6hCEDCxrZhB6vjEVOkv2gzpFPgpA,882
+brickly/runtime.py,sha256=lHnILaNrUipJ6nDLiv8gAaHh9NdxCLZaR69eC8XLgN0,9290
+brickly/system.py,sha256=lMfMHR4bfaGXolPIpfoLWn32QJpMbqGyumSPNWoOE8Y,3953
+brickly_sdk-0.1.0.dist-info/METADATA,sha256=bk0_L4wVkCE1tYvckKk2jriX_E2GP6Uj7Lr0fRTF8AI,7116
+brickly_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+brickly_sdk-0.1.0.dist-info/RECORD,,

brickly_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any