@neoline/hostbridge 1.4.4 → 2.0.0

package/src/server_control_mcp/policy.py

@@ -167,6 +167,7 @@ def audit_event(
     event: str,
     session_id: str | None = None,
     host_id: str | None = None,
+    owner_agent_id: str | None = None,
     command: str | None = None,
     task_id: str | None = None,
     outcome: str | None = None,
@@ -177,6 +178,7 @@ def audit_event(
     for key, value in {
         "session_id": session_id,
         "host_id": host_id,
+        "owner_agent_id": owner_agent_id,
         "command": command,
         "task_id": task_id,
         "outcome": outcome,

package/src/server_control_mcp/protocol.py

@@ -0,0 +1,362 @@
+"""Versioned wire models for the HostBridge daemon protocol."""
+
+from __future__ import annotations
+
+import json
+import struct
+import threading
+import uuid
+from dataclasses import dataclass, field
+from enum import IntFlag
+from typing import Any, BinaryIO
+
+PROTOCOL_VERSION = 1
+MAX_FRAME_BYTES = 1024 * 1024
+MAX_STREAM_ID_BYTES = 4096
+_FRAME_MAGIC = b"HBV1"
+_FRAME_HEADER = struct.Struct("!4sBBHIII")
+
+
+class ProtocolError(ValueError):
+    """Raised when a wire message does not conform to protocol v1."""
+
+
+class FrameFlags(IntFlag):
+    DATA = 1
+    EOF = 2
+    CANCEL = 4
+
+
+@dataclass(frozen=True, slots=True)
+class BinaryFrame:
+    stream_id: str
+    sequence: int
+    flags: FrameFlags
+    payload: bytes = b""
+
+
+def encode_frame(frame: BinaryFrame) -> bytes:
+    stream_id = _required_text(frame.stream_id, "stream_id").encode("utf-8")
+    if len(stream_id) > MAX_STREAM_ID_BYTES:
+        raise ProtocolError(f"stream_id exceeds {MAX_STREAM_ID_BYTES} bytes")
+    if not isinstance(frame.sequence, int) or isinstance(frame.sequence, bool) or frame.sequence < 0:
+        raise ProtocolError("sequence must be a non-negative integer")
+    if frame.sequence > 0xFFFFFFFF:
+        raise ProtocolError("sequence exceeds frame limit")
+    if not isinstance(frame.flags, FrameFlags) or not frame.flags:
+        raise ProtocolError("flags must contain a supported frame flag")
+    if int(frame.flags) & ~int(FrameFlags.DATA | FrameFlags.EOF | FrameFlags.CANCEL):
+        raise ProtocolError("flags contain an unsupported frame flag")
+    if not isinstance(frame.payload, bytes):
+        raise ProtocolError("frame payload must be bytes")
+    if len(frame.payload) > MAX_FRAME_BYTES:
+        raise ProtocolError(f"frame payload exceeds {MAX_FRAME_BYTES} bytes")
+    header = _FRAME_HEADER.pack(
+        _FRAME_MAGIC,
+        PROTOCOL_VERSION,
+        int(frame.flags),
+        0,
+        frame.sequence,
+        len(stream_id),
+        len(frame.payload),
+    )
+    return header + stream_id + frame.payload
+
+
+def decode_frame(data: bytes) -> tuple[BinaryFrame, bytes]:
+    if not isinstance(data, bytes):
+        raise ProtocolError("frame data must be bytes")
+    if len(data) < _FRAME_HEADER.size:
+        raise ProtocolError("incomplete frame header")
+    magic, protocol, raw_flags, reserved, sequence, stream_id_length, payload_length = _FRAME_HEADER.unpack_from(data)
+    if magic != _FRAME_MAGIC:
+        raise ProtocolError("invalid frame magic")
+    if protocol != PROTOCOL_VERSION:
+        raise ProtocolError(f"unsupported protocol: {protocol!r}")
+    if reserved != 0:
+        raise ProtocolError("reserved frame bits must be zero")
+    if stream_id_length > MAX_STREAM_ID_BYTES:
+        raise ProtocolError(f"stream_id exceeds {MAX_STREAM_ID_BYTES} bytes")
+    if payload_length > MAX_FRAME_BYTES:
+        raise ProtocolError(f"frame payload exceeds {MAX_FRAME_BYTES} bytes")
+    frame_length = _FRAME_HEADER.size + stream_id_length + payload_length
+    if len(data) < frame_length:
+        raise ProtocolError("incomplete frame payload")
+    stream_id_start = _FRAME_HEADER.size
+    payload_start = stream_id_start + stream_id_length
+    try:
+        stream_id = data[stream_id_start:payload_start].decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ProtocolError("stream_id must be valid UTF-8") from exc
+    try:
+        flags = FrameFlags(raw_flags)
+    except ValueError as exc:
+        raise ProtocolError("flags contain an unsupported frame flag") from exc
+    if not flags or int(flags) & ~int(FrameFlags.DATA | FrameFlags.EOF | FrameFlags.CANCEL):
+        raise ProtocolError("flags contain an unsupported frame flag")
+    payload = data[payload_start:frame_length]
+    return BinaryFrame(_required_text(stream_id, "stream_id"), sequence, flags, payload), data[frame_length:]
+
+
+def _read_exact(stream: BinaryIO, size: int) -> bytes:
+    chunks = bytearray()
+    while len(chunks) < size:
+        chunk = stream.read(size - len(chunks))
+        if not chunk:
+            raise ProtocolError("incomplete frame")
+        chunks.extend(chunk)
+    return bytes(chunks)
+
+
+def read_frame(stream: BinaryIO) -> BinaryFrame:
+    header = _read_exact(stream, _FRAME_HEADER.size)
+    _, _, _, _, _, stream_id_length, payload_length = _FRAME_HEADER.unpack(header)
+    if stream_id_length > MAX_STREAM_ID_BYTES or payload_length > MAX_FRAME_BYTES:
+        decode_frame(header)
+    body = _read_exact(stream, stream_id_length + payload_length)
+    frame, remainder = decode_frame(header + body)
+    if remainder:
+        raise ProtocolError("frame reader consumed trailing bytes")
+    return frame
+
+
+class StreamWindow:
+    """Thread-safe credit window used to apply stream backpressure."""
+
+    def __init__(self, initial_credit: int):
+        if not isinstance(initial_credit, int) or isinstance(initial_credit, bool) or initial_credit < 0:
+            raise ValueError("initial_credit must be a non-negative integer")
+        self._credit = initial_credit
+        self._closed = False
+        self._condition = threading.Condition()
+
+    def acquire_nowait(self) -> bool:
+        with self._condition:
+            if self._closed or self._credit == 0:
+                return False
+            self._credit -= 1
+            return True
+
+    def acquire(self, timeout: float | None = None) -> bool:
+        with self._condition:
+            ready = self._condition.wait_for(lambda: self._closed or self._credit > 0, timeout=timeout)
+            if not ready or self._closed:
+                return False
+            self._credit -= 1
+            return True
+
+    def ack(self, count: int = 1) -> None:
+        if not isinstance(count, int) or isinstance(count, bool) or count <= 0:
+            raise ValueError("count must be a positive integer")
+        with self._condition:
+            if self._closed:
+                return
+            self._credit += count
+            self._condition.notify_all()
+
+    def close(self) -> None:
+        with self._condition:
+            self._closed = True
+            self._condition.notify_all()
+
+
+class FrameSequenceValidator:
+    """Reject missing or repeated frames independently for each stream."""
+
+    def __init__(self) -> None:
+        self._next_by_stream: dict[str, int] = {}
+
+    def accept(self, frame: BinaryFrame) -> None:
+        expected = self._next_by_stream.get(frame.stream_id, 0)
+        if frame.sequence != expected:
+            raise ProtocolError(
+                f"stream {frame.stream_id!r} expected sequence {expected}, received {frame.sequence}"
+            )
+        self._next_by_stream[frame.stream_id] = expected + 1
+
+
+def _parse_object(payload: str) -> dict[str, Any]:
+    try:
+        value = json.loads(payload)
+    except (json.JSONDecodeError, TypeError) as exc:
+        raise ProtocolError("invalid JSON object") from exc
+    if not isinstance(value, dict):
+        raise ProtocolError("message must be a JSON object")
+    return value
+
+
+def _required_text(value: object, field: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ProtocolError(f"{field} must be a non-empty string")
+    return value
+
+
+def _protocol(value: dict[str, Any]) -> int:
+    protocol = value.get("protocol")
+    if protocol != PROTOCOL_VERSION:
+        raise ProtocolError(f"unsupported protocol: {protocol!r}")
+    return PROTOCOL_VERSION
+
+
+def _object(value: object, field_name: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise ProtocolError(f"{field_name} must be a JSON object")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorInfo:
+    code: str
+    message: str
+    retryable: bool = False
+    details: dict[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, value: object) -> ErrorInfo:
+        data = _object(value, "error")
+        retryable = data.get("retryable", False)
+        if not isinstance(retryable, bool):
+            raise ProtocolError("error.retryable must be a boolean")
+        return cls(
+            code=_required_text(data.get("code"), "error.code"),
+            message=_required_text(data.get("message"), "error.message"),
+            retryable=retryable,
+            details=_object(data.get("details", {}), "error.details"),
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "retryable": self.retryable,
+            "details": self.details,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class Request:
+    protocol: int
+    request_id: str
+    method: str
+    params: dict[str, object]
+
+    @classmethod
+    def new(
+        cls,
+        method: str,
+        params: dict[str, object],
+        *,
+        request_id: str | None = None,
+    ) -> Request:
+        return cls(
+            protocol=PROTOCOL_VERSION,
+            request_id=_required_text(request_id or uuid.uuid4().hex, "request_id"),
+            method=_required_text(method, "method"),
+            params=dict(params),
+        )
+
+    @classmethod
+    def from_json(cls, payload: str) -> Request:
+        value = _parse_object(payload)
+        return cls(
+            protocol=_protocol(value),
+            request_id=_required_text(value.get("request_id"), "request_id"),
+            method=_required_text(value.get("method"), "method"),
+            params=_object(value.get("params"), "params"),
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {
+                "protocol": self.protocol,
+                "request_id": self.request_id,
+                "method": self.method,
+                "params": self.params,
+            },
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    protocol: int
+    request_id: str
+    ok: bool
+    result: dict[str, object] = field(default_factory=dict)
+    error: ErrorInfo | None = None
+
+    @classmethod
+    def success(cls, request_id: str, result: dict[str, object]) -> Response:
+        return cls(PROTOCOL_VERSION, _required_text(request_id, "request_id"), True, dict(result))
+
+    @classmethod
+    def failure(cls, request_id: str, error: ErrorInfo) -> Response:
+        return cls(PROTOCOL_VERSION, _required_text(request_id, "request_id"), False, {}, error)
+
+    @classmethod
+    def from_json(cls, payload: str) -> Response:
+        value = _parse_object(payload)
+        ok = value.get("ok")
+        if not isinstance(ok, bool):
+            raise ProtocolError("ok must be a boolean")
+        request_id = _required_text(value.get("request_id"), "request_id")
+        protocol = _protocol(value)
+        if ok:
+            if value.get("error") is not None:
+                raise ProtocolError("successful response must not contain error")
+            return cls(protocol, request_id, True, _object(value.get("result", {}), "result"))
+        if value.get("result") not in (None, {}):
+            raise ProtocolError("failed response must not contain result")
+        return cls(protocol, request_id, False, {}, ErrorInfo.from_dict(value.get("error")))
+
+    def to_json(self) -> str:
+        payload: dict[str, object] = {
+            "protocol": self.protocol,
+            "request_id": self.request_id,
+            "ok": self.ok,
+        }
+        if self.ok:
+            payload["result"] = self.result
+        elif self.error is not None:
+            payload["error"] = self.error.to_dict()
+        return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    protocol: int
+    request_id: str
+    stream_id: str
+    sequence: int
+    event: str
+    data: dict[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, payload: str) -> Event:
+        value = _parse_object(payload)
+        sequence = value.get("sequence")
+        if not isinstance(sequence, int) or isinstance(sequence, bool) or sequence < 0:
+            raise ProtocolError("sequence must be a non-negative integer")
+        return cls(
+            protocol=_protocol(value),
+            request_id=_required_text(value.get("request_id"), "request_id"),
+            stream_id=_required_text(value.get("stream_id"), "stream_id"),
+            sequence=sequence,
+            event=_required_text(value.get("event"), "event"),
+            data=_object(value.get("data", {}), "data"),
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {
+                "protocol": self.protocol,
+                "request_id": self.request_id,
+                "stream_id": self.stream_id,
+                "sequence": self.sequence,
+                "event": self.event,
+                "data": self.data,
+            },
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )

package/src/server_control_mcp/runtime.py

@@ -0,0 +1,40 @@
+"""Runtime paths and process metadata for the HostBridge daemon."""
+
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimePaths:
+    directory: Path
+    socket: Path
+    pid: Path
+    log: Path
+
+    def ensure_directory(self) -> None:
+        self.directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+        self.directory.chmod(0o700)
+
+
+def _default_runtime_dir() -> Path:
+    username = os.environ.get("USER") or os.environ.get("LOGNAME") or getpass.getuser() or "user"
+    base = Path("/private/tmp") if sys.platform == "darwin" else Path(tempfile.gettempdir())
+    return base / f"hostbridge-{username}"
+
+
+def runtime_paths(socket_path: Path | str | None = None) -> RuntimePaths:
+    configured_socket = socket_path or os.environ.get("HOSTBRIDGE_DAEMON_SOCKET")
+    if configured_socket:
+        socket = Path(configured_socket).expanduser()
+        directory = socket.parent
+    else:
+        configured_dir = os.environ.get("HOSTBRIDGE_DAEMON_DIR")
+        directory = Path(configured_dir).expanduser() if configured_dir else _default_runtime_dir()
+        socket = directory / "daemon.sock"
+    return RuntimePaths(directory, socket, directory / "daemon.pid", directory / "daemon.log")