@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/mcp_notification_wait_policy.py

@@ -0,0 +1,159 @@
+"""Bound and deduplicate long-running MCP notification wait tool calls."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from threading import Lock, RLock
+from typing import Any, Callable
+
+
+WAIT_TOOL_NAMES = frozenset(
+    {
+        "wait_for_notification",
+        "wait_for_notifications",
+        "wait_for_message",
+        "wait_for_messages",
+        "wait_for_event",
+        "wait_for_events",
+        "wait_for_response",
+        "wait_for_responses",
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class McpNotificationWaitPolicy:
+    env: Callable[[str], str | None]
+
+    def timeout_cap_ms(self) -> int:
+        return self._bounded_int(
+            "CIEL_RUNTIME_MCP_NOTIFICATION_WAIT_TIMEOUT_MS", 1000, 100, 10_000
+        )
+
+    def duplicate_cap_ms(self) -> int:
+        return self._bounded_int(
+            "CIEL_RUNTIME_MCP_NOTIFICATION_WAIT_DUPLICATE_TIMEOUT_MS", 100, 50, 5000
+        )
+
+    def duplicate_window_seconds(self) -> float:
+        raw = self.env("CIEL_RUNTIME_MCP_NOTIFICATION_WAIT_DUPLICATE_WINDOW_SECONDS")
+        if raw is None:
+            return 90.0
+        try:
+            value = float(str(raw).strip())
+        except (TypeError, ValueError):
+            return 90.0
+        return max(0.0, min(600.0, value))
+
+    def _bounded_int(self, name: str, default: int, minimum: int, maximum: int) -> int:
+        raw = self.env(name)
+        if raw is None:
+            return default
+        try:
+            value = int(float(str(raw).strip()))
+        except (TypeError, ValueError):
+            return default
+        return 0 if value <= 0 else max(minimum, min(maximum, value))
+
+
+class McpNotificationWaitRepository:
+    def __init__(self, recent: dict[str, float], lock: Lock | RLock) -> None:
+        self.recent = recent
+        self._lock = lock
+
+    def mark_and_is_duplicate(self, key: str, now: float, window: float) -> bool:
+        with self._lock:
+            stale = [name for name, seen_at in self.recent.items() if now - seen_at > window]
+            for name in stale:
+                self.recent.pop(name, None)
+            previous = self.recent.get(key)
+            duplicate = previous is not None and now - previous <= window
+            self.recent[key] = now
+            return duplicate
+
+
+@dataclass(frozen=True, slots=True)
+class McpNotificationWaitPorts:
+    lookup_schema: Callable[[str], dict[str, Any] | None]
+    now: Callable[[], float]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class McpNotificationWaitService:
+    policy: McpNotificationWaitPolicy
+    repository: McpNotificationWaitRepository
+    ports: McpNotificationWaitPorts
+
+    @staticmethod
+    def tool_leaf_name(tool_name: str) -> str:
+        text = str(tool_name or "").strip()
+        return text.rsplit("__", 1)[-1].strip().lower() if "__" in text else text.lower()
+
+    def is_wait_tool(self, tool_name: str) -> bool:
+        text = str(tool_name or "").strip().lower()
+        return text.startswith("mcp__") and self.tool_leaf_name(text) in WAIT_TOOL_NAMES
+
+    def effective_cap_ms(self, tool_name: str) -> tuple[int, bool]:
+        cap_ms = self.policy.timeout_cap_ms()
+        if cap_ms <= 0:
+            return 0, False
+        duplicate_cap_ms = self.policy.duplicate_cap_ms()
+        window = self.policy.duplicate_window_seconds()
+        if duplicate_cap_ms <= 0 or window <= 0:
+            return cap_ms, False
+        key = str(tool_name or "").strip().lower()
+        duplicate = self.repository.mark_and_is_duplicate(key, self.ports.now(), window)
+        return (min(cap_ms, duplicate_cap_ms), True) if duplicate else (cap_ms, False)
+
+    def cap_input(self, tool_name: str, tool_input: dict[str, Any]) -> dict[str, Any]:
+        if not self.is_wait_tool(tool_name):
+            return tool_input
+        cap_ms, duplicate = self.effective_cap_ms(tool_name)
+        if cap_ms <= 0:
+            return tool_input
+        fixed = dict(tool_input) if isinstance(tool_input, dict) else {}
+        schema = self.ports.lookup_schema(tool_name) or {}
+        properties = schema.get("properties") if isinstance(schema.get("properties"), dict) else {}
+        changed: list[str] = []
+        for key in list(fixed):
+            key_lower = str(key).strip().lower()
+            if key_lower in {"timeout_ms", "timeoutms", "wait_ms", "waitms", "max_wait_ms", "maxwaitms"}:
+                self._set_if_lower(fixed, changed, key, cap_ms)
+            elif key_lower in {"timeout", "wait_seconds", "wait_s", "max_wait_seconds"}:
+                self._set_if_lower(fixed, changed, key, max(0.1, cap_ms / 1000.0))
+        if not changed:
+            if "timeout_ms" in properties or "timeout_ms" in fixed or not properties:
+                self._set_if_lower(fixed, changed, "timeout_ms", cap_ms)
+            elif "timeout" in properties:
+                self._set_if_lower(fixed, changed, "timeout", max(0.1, cap_ms / 1000.0))
+        if changed:
+            duplicate_label = " duplicate=true" if duplicate else ""
+            self.ports.log(
+                "INFO",
+                f"mcp_notification_wait_timeout_capped tool={tool_name}{duplicate_label} {' '.join(changed)}",
+            )
+        return fixed
+
+    @staticmethod
+    def _set_if_lower(
+        target: dict[str, Any], changed: list[str], key: str, value: int | float
+    ) -> None:
+        old = target.get(key)
+        try:
+            numeric = float(old)
+        except Exception:
+            target[key] = int(value) if float(value).is_integer() else value
+            changed.append(f"{key}=missing->{value:g}")
+            return
+        if numeric > float(value):
+            target[key] = int(value) if float(value).is_integer() else value
+            changed.append(f"{key}={numeric:g}->{value:g}")
+
+
+__all__ = [
+    "McpNotificationWaitPolicy",
+    "McpNotificationWaitPorts",
+    "McpNotificationWaitRepository",
+    "McpNotificationWaitService",
+    "WAIT_TOOL_NAMES",
+]

package/ciel_runtime_support/mcp_probe_codec.py

@@ -0,0 +1,136 @@
+"""Pure codecs and capability rules used by MCP channel probes."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def probe_strategy(server: dict[str, Any]) -> str:
+    """Select JSONL by default, with explicit legacy LSP framing opt-in."""
+
+    if not isinstance(server, dict):
+        return "jsonl"
+    mode = str(server.get("ciel_runtime_stdio") or server.get("stdio_mode") or "").strip().lower()
+    return "framed" if mode in ("framed", "framed-only", "content-length", "lsp") else "jsonl"
+
+
+def initialize_payload(client_version: str, protocol_version: str = "2024-11-05") -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": protocol_version,
+            "capabilities": {},
+            "clientInfo": {"name": "ciel-runtime-channel-probe", "version": client_version},
+        },
+    }
+
+
+def initialize_payload_bytes(client_version: str, protocol_version: str = "2024-11-05") -> bytes:
+    return json.dumps(
+        initialize_payload(client_version, protocol_version),
+        ensure_ascii=False,
+    ).encode("utf-8")
+
+
+def parse_framed_responses(buffer: bytes) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    index = 0
+    while index < len(buffer):
+        header_end = buffer.find(b"\r\n\r\n", index)
+        if header_end < 0:
+            return out
+        header = buffer[index:header_end].decode("ascii", errors="replace")
+        length = _content_length(header)
+        if length is None:
+            return out
+        body_start = header_end + 4
+        body_end = body_start + length
+        if len(buffer) < body_end:
+            return out
+        message = _json_object(buffer[body_start:body_end])
+        if message is not None:
+            out.append(message)
+        index = body_end
+    return out
+
+
+def _content_length(header: str) -> int | None:
+    for line in header.split("\r\n"):
+        if not line.lower().startswith("content-length:"):
+            continue
+        try:
+            value = int(line.split(":", 1)[1].strip())
+        except (IndexError, TypeError, ValueError):
+            return None
+        return value if value >= 0 else None
+    return None
+
+
+def _json_object(raw: bytes) -> dict[str, Any] | None:
+    try:
+        message = json.loads(raw.decode("utf-8", errors="replace"))
+    except (TypeError, ValueError, json.JSONDecodeError):
+        return None
+    return message if isinstance(message, dict) else None
+
+
+def parse_jsonl_responses(buffer: bytes) -> list[dict[str, Any]]:
+    return [
+        message
+        for raw_line in buffer.split(b"\n")
+        if raw_line.strip()
+        for message in [_json_object(raw_line.strip())]
+        if message is not None
+    ]
+
+
+def find_initialize_response(buffer: bytes, framed: bool) -> dict[str, Any] | None:
+    messages = parse_framed_responses(buffer) if framed else parse_jsonl_responses(buffer)
+    return next((message for message in messages if message.get("id") == 1 and "result" in message), None)
+
+
+def channel_capability_present(initialize_response: dict[str, Any]) -> bool:
+    result = initialize_response.get("result")
+    capabilities = result.get("capabilities") if isinstance(result, dict) else None
+    experimental = capabilities.get("experimental") if isinstance(capabilities, dict) else None
+    value = experimental.get("claude/channel") if isinstance(experimental, dict) else None
+    return value is not None and value is not False
+
+
+def decode_sse_events(buffer: bytearray) -> tuple[list[tuple[str, str]], bytearray]:
+    """Drain complete SSE events and return the incomplete byte remainder."""
+
+    events: list[tuple[str, str]] = []
+    text = bytes(buffer).decode("utf-8", errors="replace").replace("\r\n", "\n").replace("\r", "\n")
+    while True:
+        separator = text.find("\n\n")
+        if separator < 0:
+            break
+        event_text, text = text[:separator], text[separator + 2:]
+        event_name = "message"
+        data_lines: list[str] = []
+        for line in event_text.split("\n"):
+            if not line or line.startswith(":"):
+                continue
+            if line.startswith("event:"):
+                event_name = line[len("event:"):].lstrip()
+            elif line.startswith("data:"):
+                payload = line[len("data:"):]
+                data_lines.append(payload[1:] if payload.startswith(" ") else payload)
+        events.append((event_name, "\n".join(data_lines)))
+    return events, bytearray(text.encode("utf-8"))
+
+
+__all__ = [
+    "channel_capability_present",
+    "decode_sse_events",
+    "find_initialize_response",
+    "initialize_payload",
+    "initialize_payload_bytes",
+    "parse_framed_responses",
+    "parse_jsonl_responses",
+    "probe_strategy",
+]

package/ciel_runtime_support/mcp_probe_transport.py

@@ -0,0 +1,328 @@
+"""SSE and Streamable HTTP MCP capability probe transports."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import queue
+import threading
+import time
+from typing import Any, Callable
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+@dataclass(frozen=True, slots=True)
+class McpProbeCodec:
+    initialize_bytes: Callable[..., bytes]
+    initialize_dict: Callable[..., dict[str, Any]]
+    decode_sse_events: Callable[..., tuple[list[tuple[str, str]], bytearray]]
+    capability_present: Callable[..., bool]
+    decode_preview: Callable[..., str]
+
+
+@dataclass(frozen=True, slots=True)
+class McpProbeHttp:
+    runtime_headers: Callable[..., dict[str, str]]
+    urlopen: Callable[..., Any]
+    streamable_post_json: Callable[..., Any]
+    delete_streamable_session: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class McpProbePolicy:
+    default_timeout: Callable[[], float]
+    stderr_preview_chars: int
+    stdout_preview_bytes: int
+    sse_open_timeout_seconds: float
+    sse_init_post_timeout_seconds: float
+    streamable_protocol_version: str
+
+
+@dataclass(frozen=True, slots=True)
+class McpProbeServices:
+    codec: McpProbeCodec
+    http: McpProbeHttp
+    policy: McpProbePolicy
+    log: Callable[[str, str], Any]
+
+
+def _empty_result(reason: str) -> dict[str, Any]:
+    return {
+        "capable": False,
+        "reason": reason,
+        "response_bytes": 0,
+        "response_received": False,
+        "elapsed_ms": 0,
+        "exit_code": None,
+        "stderr_bytes": 0,
+        "stderr_preview": "",
+        "stdout_preview": "",
+    }
+
+
+def probe_sse_mcp_for_channel_capability_detailed(
+    server_name: str,
+    server: dict[str, Any],
+    timeout: float | None = None,
+    *,
+    services: McpProbeServices,
+) -> dict[str, Any]:
+    started = time.time()
+    url = str(server.get("url") or "").strip()
+    if not url:
+        return _empty_result("no_url")
+    codec = services.codec
+    http = services.http
+    policy = services.policy
+    effective_timeout = timeout if timeout is not None else policy.default_timeout()
+    open_timeout = min(policy.sse_open_timeout_seconds, effective_timeout)
+    request_headers = {
+        **http.runtime_headers(server),
+        "Accept": "text/event-stream",
+        "Cache-Control": "no-cache",
+    }
+    try:
+        get_request = urllib.request.Request(url, headers=request_headers, method="GET")
+        sse_response = http.urlopen(get_request, timeout=open_timeout)
+    except Exception as exc:
+        result = _empty_result(f"sse_open_failed:{type(exc).__name__}")
+        result["elapsed_ms"] = int((time.time() - started) * 1000)
+        result["stderr_preview"] = str(exc)[:policy.stderr_preview_chars]
+        return result
+
+    chunks: queue.Queue[bytes | None] = queue.Queue()
+
+    def read_sse() -> None:
+        try:
+            while True:
+                line = sse_response.readline()
+                if not line:
+                    break
+                chunks.put(line)
+        except Exception as exc:
+            services.log(
+                "DEBUG",
+                f"channel_probe_sse_reader_failed server={server_name} error={type(exc).__name__}: {exc}",
+            )
+        finally:
+            chunks.put(None)
+
+    threading.Thread(target=read_sse, daemon=True, name=f"channel-probe-sse-{server_name}").start()
+    deadline = time.time() + effective_timeout
+    sse_buffer = bytearray()
+    bytes_seen = 0
+    endpoint_url: str | None = None
+    init_posted = False
+    init_post_error: str | None = None
+    capable = False
+    response_received = False
+    response_data_preview = ""
+    post_headers = {"Content-Type": "application/json"}
+    for key, value in request_headers.items():
+        if key.lower() not in ("accept", "cache-control"):
+            post_headers[key] = value
+    try:
+        while time.time() < deadline:
+            wait = min(0.2, max(0.001, deadline - time.time()))
+            try:
+                chunk = chunks.get(timeout=wait)
+            except queue.Empty:
+                continue
+            if chunk is None:
+                break
+            sse_buffer.extend(chunk)
+            bytes_seen += len(chunk)
+            events, sse_buffer = codec.decode_sse_events(sse_buffer)
+            for event_name, data_text in events:
+                if not init_posted and event_name == "endpoint":
+                    target = data_text.strip()
+                    if not target:
+                        continue
+                    endpoint_url = urllib.parse.urljoin(url, target)
+                    try:
+                        post_request = urllib.request.Request(
+                            endpoint_url,
+                            data=codec.initialize_bytes(),
+                            headers=post_headers,
+                            method="POST",
+                        )
+                        with http.urlopen(
+                            post_request,
+                            timeout=min(policy.sse_init_post_timeout_seconds, max(1.0, deadline - time.time())),
+                        ) as post_response:
+                            post_response.read()
+                        init_posted = True
+                    except Exception as exc:
+                        init_post_error = f"{type(exc).__name__}: {exc}"
+                        break
+                    continue
+                if not init_posted or not data_text:
+                    continue
+                try:
+                    message = json.loads(data_text)
+                except (TypeError, ValueError):
+                    continue
+                if not isinstance(message, dict):
+                    continue
+                if message.get("id") == 1 and "result" in message:
+                    response_received = True
+                    capable = codec.capability_present(message)
+                    response_data_preview = codec.decode_preview(
+                        data_text.encode("utf-8"), policy.stdout_preview_bytes
+                    )
+                    break
+            if response_received or init_post_error:
+                break
+    finally:
+        try:
+            sse_response.close()
+        except Exception as exc:
+            services.log(
+                "DEBUG",
+                f"channel_probe_sse_close_failed server={server_name} error={type(exc).__name__}: {exc}",
+            )
+    elapsed_ms = int((time.time() - started) * 1000)
+    if capable:
+        reason = "capable"
+    elif response_received:
+        reason = "no_experimental_claude_channel"
+    elif init_post_error:
+        reason = f"sse_init_post_failed:{init_post_error.split(':', 1)[0]}"
+    elif init_posted:
+        reason = "timeout_waiting_for_initialize_response"
+    elif endpoint_url:
+        reason = "timeout_after_endpoint_event"
+    else:
+        reason = "timeout_no_endpoint_event"
+    stderr_preview = init_post_error[:policy.stderr_preview_chars] if init_post_error else ""
+    stdout_preview = response_data_preview if response_data_preview and not capable else ""
+    services.log(
+        "INFO",
+        "channel_probe_result server=%s channel_capable=%s reason=%s transport=sse url=%s bytes=%d elapsed_ms=%d timeout_s=%.1f"
+        % (server_name, capable, reason, url, bytes_seen, elapsed_ms, effective_timeout),
+    )
+    if stderr_preview:
+        services.log("INFO", f"channel_probe_sse_error server={server_name} preview={stderr_preview!r}")
+    return {
+        "capable": capable,
+        "reason": reason,
+        "response_bytes": bytes_seen,
+        "response_received": response_received,
+        "elapsed_ms": elapsed_ms,
+        "exit_code": None,
+        "stderr_bytes": len(stderr_preview),
+        "stderr_preview": stderr_preview,
+        "stdout_preview": stdout_preview,
+    }
+
+
+def probe_streamable_http_mcp_for_channel_capability_detailed(
+    server_name: str,
+    server: dict[str, Any],
+    timeout: float | None = None,
+    *,
+    services: McpProbeServices,
+) -> dict[str, Any]:
+    started = time.time()
+    url = str(server.get("url") or server.get("endpoint") or "").strip()
+    if not url:
+        return _empty_result("no_url")
+    codec = services.codec
+    http = services.http
+    policy = services.policy
+    effective_timeout = timeout if timeout is not None else policy.default_timeout()
+    protocol_version = str(
+        server.get("protocolVersion")
+        or server.get("protocol_version")
+        or policy.streamable_protocol_version
+    )
+    headers = http.runtime_headers(server)
+    bytes_seen = 0
+    response_received = False
+    capable = False
+    reason = ""
+    stderr_preview = ""
+    stdout_preview = ""
+    initialized_failed = False
+    session_id: str | None = None
+    try:
+        response, session_id = http.streamable_post_json(
+            url,
+            headers,
+            codec.initialize_dict(protocol_version),
+            max(1.0, min(120.0, effective_timeout)),
+            protocol_version,
+        )
+        preview_source = json.dumps(response, ensure_ascii=False) if isinstance(response, (dict, list)) else str(response or "")
+        bytes_seen = len(preview_source.encode("utf-8", errors="replace"))
+        if isinstance(response, dict) and response.get("id") == 1 and "result" in response:
+            response_received = True
+            capable = codec.capability_present(response)
+            if not capable:
+                stdout_preview = codec.decode_preview(preview_source.encode("utf-8"), policy.stdout_preview_bytes)
+        else:
+            stdout_preview = codec.decode_preview(preview_source.encode("utf-8"), policy.stdout_preview_bytes)
+        if response_received:
+            try:
+                http.streamable_post_json(
+                    url,
+                    headers,
+                    {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}},
+                    max(1.0, min(120.0, effective_timeout)),
+                    protocol_version,
+                    session_id,
+                )
+            except Exception as exc:
+                initialized_failed = True
+                capable = False
+                stderr_preview = f"{type(exc).__name__}: {exc}"[:policy.stderr_preview_chars]
+        reason = "streamable_http_initialized_post_failed" if initialized_failed else (
+            "capable" if capable else ("no_experimental_claude_channel" if response_received else "no_initialize_response")
+        )
+    except urllib.error.HTTPError as exc:
+        reason = "streamable_http_405_fallback_sse" if exc.code == 405 else f"streamable_http_open_failed:HTTPError:{exc.code}"
+        try:
+            data = exc.read()
+        except Exception as read_exc:
+            services.log(
+                "DEBUG",
+                f"channel_probe_http_error_read_failed server={server_name} error={type(read_exc).__name__}: {read_exc}",
+            )
+            data = b""
+        bytes_seen = len(data)
+        stderr_preview = (data.decode("utf-8", errors="replace") or str(exc))[:policy.stderr_preview_chars]
+    except Exception as exc:
+        reason = f"streamable_http_open_failed:{type(exc).__name__}"
+        stderr_preview = str(exc)[:policy.stderr_preview_chars]
+    finally:
+        if session_id:
+            http.delete_streamable_session(
+                f"probe-{server_name}",
+                url,
+                headers,
+                protocol_version,
+                session_id,
+                "channel_probe_cleanup",
+                timeout=min(10.0, max(1.0, effective_timeout)),
+            )
+    elapsed_ms = int((time.time() - started) * 1000)
+    services.log(
+        "INFO",
+        "channel_probe_result server=%s channel_capable=%s reason=%s transport=streamable-http url=%s bytes=%d elapsed_ms=%d timeout_s=%.1f"
+        % (server_name, capable, reason, url, bytes_seen, elapsed_ms, effective_timeout),
+    )
+    if stderr_preview:
+        services.log("INFO", f"channel_probe_streamable_http_error server={server_name} preview={stderr_preview!r}")
+    return {
+        "capable": capable,
+        "reason": reason,
+        "response_bytes": bytes_seen,
+        "response_received": response_received,
+        "elapsed_ms": elapsed_ms,
+        "exit_code": None,
+        "stderr_bytes": len(stderr_preview),
+        "stderr_preview": stderr_preview,
+        "stdout_preview": stdout_preview,
+    }