@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/channel_connection_worker.py

@@ -0,0 +1,284 @@
+"""Network workers for SSE and MCP Streamable HTTP channel connections."""
+
+from __future__ import annotations
+
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from threading import Lock
+from typing import Any, Callable
+
+from ciel_runtime_support.sse_stream import SseRetryState, SseStreamServices, consume_sse_stream
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelWorkerEffects:
+    log: Callable[[str, str], None]
+    dispatch: Callable[[str, str, list[str], str | None], None]
+    set_state: Callable[..., None]
+    initialize_streamable: Callable[[str], None]
+    close_state_session: Callable[[dict[str, Any], str], None]
+    streamable_headers: Callable[[dict[str, str], str, str | None, str], dict[str, str]]
+    session_not_found: Callable[[urllib.error.HTTPError, str], bool]
+    http_error_body: Callable[[urllib.error.HTTPError], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelWorkerPolicy:
+    streamable_protocol_version: str
+    legacy_sse_protocol_version: str
+    parse_bool: Callable[[Any, bool], bool]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelWorkerStateStore:
+    states: dict[str, dict[str, Any]]
+    lock: Lock
+
+    @staticmethod
+    def _matches(state: dict[str, Any], connection_id: str | None) -> bool:
+        return not connection_id or str(state.get("connection_id") or "") == str(connection_id)
+
+    def snapshot(self, name: str, connection_id: str | None) -> dict[str, Any] | None:
+        with self.lock:
+            state = self.states.get(name)
+            if not state or not state.get("running") or not self._matches(state, connection_id):
+                return None
+            return dict(state)
+
+    def running(self, name: str, connection_id: str | None) -> bool:
+        return self.snapshot(name, connection_id) is not None
+
+    def record_reconnect(
+        self,
+        name: str,
+        connection_id: str | None,
+        error: str,
+    ) -> str | None:
+        with self.lock:
+            state = self.states.get(name)
+            if not state or not state.get("running") or not self._matches(state, connection_id):
+                return None
+            state["last_error"] = error
+            state["sse_reconnects"] = int(state.get("sse_reconnects") or 0) + 1
+            event_id = state.get("last_sse_event_id")
+            return str(event_id) if event_id is not None and str(event_id) != "" else "-"
+
+    def state_after_initialize(
+        self,
+        name: str,
+        connection_id: str | None,
+        parse_bool: Callable[[Any, bool], bool],
+    ) -> tuple[str, str | None] | None:
+        with self.lock:
+            state = self.states.get(name)
+            if not state or not state.get("running") or not self._matches(state, connection_id):
+                return None
+            if str(state.get("transport") or "").strip().lower() == "sse":
+                return "sse", None
+            if not state.get("mcp_initialized"):
+                return "retry", None
+            session_id = str(state.get("mcp_session_id") or "").strip() or None
+            if parse_bool(state.get("streamable_requires_session"), True) and not session_id:
+                state["mcp_initialized"] = False
+                state["mcp_last_error"] = "streamable_http_missing_session_id"
+                return "retry", None
+            return "ready", session_id
+
+    def record_http_error(
+        self,
+        name: str,
+        connection_id: str | None,
+        error: urllib.error.HTTPError,
+        session_not_found: bool,
+        legacy_protocol_version: str,
+    ) -> tuple[str, str] | None:
+        with self.lock:
+            state = self.states.get(name)
+            if not state or not state.get("running") or not self._matches(state, connection_id):
+                return None
+            if error.code == 405:
+                state.update(
+                    transport="sse",
+                    mcp_protocol_version=legacy_protocol_version,
+                    mcp_initialized=False,
+                    mcp_session_id=None,
+                    last_error="streamable_http_405_fallback_sse",
+                )
+                return "sse", "-"
+            if session_not_found:
+                state.update(
+                    mcp_initialized=False,
+                    mcp_session_id=None,
+                    mcp_last_error=f"streamable_http_session_not_found:HTTPError:{error.code}",
+                )
+            state["last_error"] = f"HTTPError: {error.code} {error.reason}"
+            state["sse_reconnects"] = int(state.get("sse_reconnects") or 0) + 1
+            event_id = state.get("last_sse_event_id")
+            resumed = str(event_id) if event_id is not None and str(event_id) != "" else "-"
+            return "retry", resumed
+
+    def state_for_close(self, name: str, connection_id: str | None) -> dict[str, Any] | None:
+        with self.lock:
+            state = self.states.get(name)
+            return dict(state) if state and self._matches(state, connection_id) else None
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelConnectionWorker:
+    state_store: ChannelWorkerStateStore
+    effects: ChannelWorkerEffects
+    policy: ChannelWorkerPolicy
+
+    @staticmethod
+    def _event_id(value: Any) -> str:
+        return str(value) if value is not None and str(value) != "" else "-"
+
+    def run_sse(self, name: str, connection_id: str | None = None) -> None:
+        while snapshot := self.state_store.snapshot(name, connection_id):
+            url = str(snapshot.get("url") or "")
+            headers = dict(snapshot.get("headers") or {})
+            last_event_id = snapshot.get("last_sse_event_id")
+            read_timeout = max(5.0, min(3600.0, float(snapshot.get("read_timeout_seconds") or 300.0)))
+            retry = SseRetryState(max(1.0, min(60.0, float(snapshot.get("retry_seconds") or 5.0))))
+            try:
+                request_headers = {**headers, "Accept": "text/event-stream"}
+                if last_event_id is not None and str(last_event_id) != "":
+                    request_headers["Last-Event-ID"] = str(last_event_id)
+                request = urllib.request.Request(url, headers=request_headers)
+                with urllib.request.urlopen(request, timeout=read_timeout) as response:
+                    self.effects.set_state(name, last_error=None)
+                    self.effects.log(
+                        "INFO",
+                        f"channel_sse_connected name={name} url={url} last_event_id={self._event_id(last_event_id)}",
+                    )
+                    consume_sse_stream(
+                        response,
+                        retry,
+                        "SSE stream ended",
+                        SseStreamServices(
+                            should_continue=lambda: self.state_store.running(name, connection_id),
+                            dispatch=lambda event, data, event_id: self.effects.dispatch(
+                                name, event, data, event_id
+                            ),
+                            invalid_retry=lambda value: self.effects.log(
+                                "WARN", f"channel_sse_invalid_retry name={name} value={value!r}"
+                            ),
+                        ),
+                    )
+            except Exception as error:
+                resumed = self.state_store.record_reconnect(
+                    name, connection_id, f"{type(error).__name__}: {error}"
+                )
+                if resumed is None:
+                    return
+                self.effects.log(
+                    "WARN",
+                    f"channel_sse_reconnect name={name} last_event_id={resumed} error={type(error).__name__}: {error}",
+                )
+                time.sleep(retry.seconds)
+
+    def run_streamable_http(self, name: str, connection_id: str | None = None) -> None:
+        switch_to_sse = False
+        try:
+            while snapshot := self.state_store.snapshot(name, connection_id):
+                url = str(snapshot.get("url") or "")
+                headers = dict(snapshot.get("headers") or {})
+                protocol_version = str(
+                    snapshot.get("mcp_protocol_version") or self.policy.streamable_protocol_version
+                )
+                session_id = str(snapshot.get("mcp_session_id") or "").strip() or None
+                requires_session = self.policy.parse_bool(snapshot.get("streamable_requires_session"), True)
+                needs_initialize = not snapshot.get("mcp_initialized") or (requires_session and not session_id)
+                last_event_id = snapshot.get("last_sse_event_id")
+                read_timeout = max(5.0, min(3600.0, float(snapshot.get("read_timeout_seconds") or 300.0)))
+                retry = SseRetryState(max(1.0, min(60.0, float(snapshot.get("retry_seconds") or 5.0))))
+                if needs_initialize:
+                    self.effects.initialize_streamable(name)
+                    initialized = self.state_store.state_after_initialize(
+                        name, connection_id, self.policy.parse_bool
+                    )
+                    if initialized is None:
+                        return
+                    outcome, session_id = initialized
+                    if outcome == "sse":
+                        self.effects.log("INFO", f"channel_http_worker_switching_to_sse name={name}")
+                        switch_to_sse = True
+                        break
+                    if outcome == "retry":
+                        time.sleep(retry.seconds)
+                        continue
+                try:
+                    request_headers = self.effects.streamable_headers(
+                        headers, protocol_version, session_id, "text/event-stream"
+                    )
+                    if last_event_id is not None and str(last_event_id) != "":
+                        request_headers["Last-Event-ID"] = str(last_event_id)
+                    request = urllib.request.Request(url, headers=request_headers, method="GET")
+                    with urllib.request.urlopen(request, timeout=read_timeout) as response:
+                        self.effects.set_state(name, last_error=None)
+                        self.effects.log(
+                            "INFO",
+                            f"channel_http_connected name={name} url={url} session={session_id or '-'} "
+                            f"last_event_id={self._event_id(last_event_id)}",
+                        )
+                        consume_sse_stream(
+                            response,
+                            retry,
+                            "Streamable HTTP SSE stream ended",
+                            SseStreamServices(
+                                should_continue=lambda: self.state_store.running(name, connection_id),
+                                dispatch=lambda event, data, event_id: self.effects.dispatch(
+                                    name, event, data, event_id
+                                ),
+                                invalid_retry=lambda value: self.effects.log(
+                                    "WARN", f"channel_http_invalid_retry name={name} value={value!r}"
+                                ),
+                            ),
+                        )
+                except urllib.error.HTTPError as error:
+                    body_text = self.effects.http_error_body(error)
+                    session_lost = self.effects.session_not_found(error, body_text)
+                    outcome = self.state_store.record_http_error(
+                        name,
+                        connection_id,
+                        error,
+                        session_lost,
+                        self.policy.legacy_sse_protocol_version,
+                    )
+                    if outcome is None:
+                        return
+                    action, resumed = outcome
+                    if action == "sse":
+                        self.effects.log(
+                            "WARN",
+                            f"channel_http_fallback_sse name={name} url={url} reason=HTTPError:405",
+                        )
+                        switch_to_sse = True
+                        break
+                    event = "session_lost_reinitialize" if session_lost else "reconnect"
+                    self.effects.log(
+                        "WARN",
+                        f"channel_http_{event} name={name} last_event_id={resumed} "
+                        f"error=HTTPError:{error.code}:{error.reason}",
+                    )
+                    time.sleep(retry.seconds)
+                except Exception as error:
+                    resumed = self.state_store.record_reconnect(
+                        name, connection_id, f"{type(error).__name__}: {error}"
+                    )
+                    if resumed is None:
+                        return
+                    self.effects.log(
+                        "WARN",
+                        f"channel_http_reconnect name={name} last_event_id={resumed} "
+                        f"error={type(error).__name__}: {error}",
+                    )
+                    time.sleep(retry.seconds)
+        finally:
+            state = self.state_store.state_for_close(name, connection_id)
+            if state and not switch_to_sse:
+                self.effects.close_state_session(state, "worker_exit")
+        if switch_to_sse:
+            self.run_sse(name, connection_id)

package/ciel_runtime_support/channel_cursor_recovery.py

@@ -0,0 +1,92 @@
+"""Recover a channel delivery cursor from queued-only transcript entries."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelCursorRecoveryPolicy:
+    cache_ttl_seconds: float = 5.0
+    transcript_max_bytes: int = 8 * 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelCursorRecoveryPorts:
+    latest_transcript: Callable[[], Path | None]
+    read_tail: Callable[..., str]
+    queued_command_ids: Callable[[str], set[int]]
+    wake_state: Callable[[int, str], str]
+    clamp_to_clear_floor: Callable[[int], int]
+    now: Callable[[], float]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelCursorRecoveryService:
+    cache: dict[str, Any]
+    policy: ChannelCursorRecoveryPolicy
+    ports: ChannelCursorRecoveryPorts
+
+    def recover(self, last_id: int) -> int:
+        if last_id <= 0:
+            return last_id
+        path = self.ports.latest_transcript()
+        if path is None:
+            return last_id
+        marker = self._file_marker(path)
+        if marker is None:
+            return last_id
+        now = self.ports.now()
+        if self._cache_is_fresh(last_id, marker, now):
+            cached = self.cache.get("recovered_last_id")
+            recovered = int(cached) if isinstance(cached, int) else last_id
+            return self.ports.clamp_to_clear_floor(recovered)
+        text = self.ports.read_tail(path, max_bytes=self.policy.transcript_max_bytes)
+        recovered = self._recover_from_text(last_id, text)
+        self.cache.update(
+            {
+                "checked_at": now,
+                "last_id": last_id,
+                "marker": marker,
+                "recovered_last_id": recovered,
+            }
+        )
+        return self.ports.clamp_to_clear_floor(recovered)
+
+    @staticmethod
+    def _file_marker(path: Path) -> tuple[str, int, int] | None:
+        try:
+            stat = path.stat()
+        except OSError:
+            return None
+        return str(path), int(stat.st_mtime_ns), int(stat.st_size)
+
+    def _cache_is_fresh(self, last_id: int, marker: tuple[str, int, int], now: float) -> bool:
+        return bool(
+            self.cache.get("last_id") == last_id
+            and self.cache.get("marker") == marker
+            and now - float(self.cache.get("checked_at") or 0.0) < self.policy.cache_ttl_seconds
+        )
+
+    def _recover_from_text(self, last_id: int, text: str) -> int:
+        if not text:
+            return last_id
+        for message_id in sorted(self.ports.queued_command_ids(text)):
+            if message_id <= last_id and self.ports.wake_state(message_id, text) == "missing":
+                recovered = max(0, message_id - 1)
+                self.ports.log(
+                    "WARN",
+                    "channel_stdin_proxy_recover_queued_only "
+                    f"message_id={message_id} cursor={last_id} recovered_cursor={recovered}",
+                )
+                return recovered
+        return last_id
+
+
+__all__ = [
+    "ChannelCursorRecoveryPolicy",
+    "ChannelCursorRecoveryPorts",
+    "ChannelCursorRecoveryService",
+]

package/ciel_runtime_support/channel_cursor_repository.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class CursorReadResolution:
+    value: int
+    persist: bool = False
+    rolled_back: bool = False
+
+
+class ChannelCursorStatePolicy:
+    """Merge durable and process-local cursor state monotonically."""
+
+    @staticmethod
+    def resolve_read(
+        file_cursor: int | None,
+        cached_cursor: int | None,
+        scan_cursor: Callable[[], int],
+    ) -> CursorReadResolution:
+        tail = max(0, scan_cursor())
+        if file_cursor is not None:
+            cursor = max(file_cursor, cached_cursor or 0)
+        elif cached_cursor is not None:
+            cursor = cached_cursor
+        else:
+            return CursorReadResolution(tail, persist=True)
+        if cursor > tail:
+            return CursorReadResolution(0, persist=True, rolled_back=True)
+        return CursorReadResolution(cursor)
+
+    @staticmethod
+    def newer(candidate: int | None, current: int) -> int | None:
+        if candidate is None or candidate <= current:
+            return None
+        return candidate
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelCursorRepository:
+    path: Path
+    log: Callable[[str, str], None]
+
+    def read(self) -> int | None:
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return None
+        except (OSError, UnicodeError, json.JSONDecodeError, TypeError) as exc:
+            self.log(
+                "WARN",
+                f"channel_cursor_read_failed path={self.path} error={type(exc).__name__}: {exc}",
+            )
+            return None
+        if not isinstance(data, dict):
+            self.log("WARN", f"channel_cursor_read_failed path={self.path} error=invalid_payload")
+            return None
+        try:
+            return max(0, int(data.get("last_id") or 0))
+        except (TypeError, ValueError) as exc:
+            self.log(
+                "WARN",
+                f"channel_cursor_read_failed path={self.path} error={type(exc).__name__}: {exc}",
+            )
+            return None
+
+    def write(self, last_id: int, *, metadata: dict[str, Any] | None = None) -> bool:
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            payload: dict[str, Any] = {"last_id": max(0, int(last_id))}
+            if metadata:
+                payload.update(metadata)
+            temporary = self.path.with_suffix(".json.tmp")
+            temporary.write_text(
+                json.dumps(payload, separators=(",", ":")) + "\n",
+                encoding="utf-8",
+            )
+            temporary.replace(self.path)
+            return True
+        except (OSError, TypeError, ValueError, OverflowError) as exc:
+            self.log(
+                "WARN",
+                f"channel_cursor_write_failed path={self.path} error={type(exc).__name__}: {exc}",
+            )
+            return False

package/ciel_runtime_support/channel_cursor_service.py

@@ -0,0 +1,178 @@
+"""Application services for durable Channel MCP cursor and resume behavior."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from ciel_runtime_support.channel_cursor_repository import ChannelCursorRepository
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelCursorServices:
+    repository: ChannelCursorRepository
+    lock: Any
+    cached: Callable[[], int | None]
+    cache: Callable[[int], None]
+    scan_tail: Callable[[], int]
+
+
+class ChannelCursorService:
+    def __init__(self, services: ChannelCursorServices) -> None:
+        self.services = services
+
+    def read_locked(self) -> int:
+        cached = self.services.cached()
+        if cached is not None:
+            return cached
+        persisted = self.services.repository.read()
+        cursor = persisted if persisted is not None else max(0, self.services.scan_tail())
+        self.services.cache(cursor)
+        if persisted is None:
+            self.services.repository.write(cursor)
+        return cursor
+
+    def ensure_initialized(self) -> int:
+        with self.services.lock:
+            return self.read_locked()
+
+    def update(self, last_id: int) -> None:
+        if last_id < 0:
+            return
+        with self.services.lock:
+            if last_id <= self.read_locked():
+                return
+            cursor = int(last_id)
+            self.services.cache(cursor)
+            self.services.repository.write(cursor)
+
+
+def parse_channel_event_id(value: Any) -> int | None:
+    text = str(value or "").strip()
+    if not text:
+        return None
+    try:
+        return max(0, int(text))
+    except (TypeError, ValueError):
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelResumeServices:
+    query_params: Callable[[Any], Mapping[str, list[str]]]
+    first_param: Callable[[Mapping[str, list[str]], str], str | None]
+    ensure_cursor: Callable[[], int]
+    update_cursor: Callable[[int], None]
+    log: Callable[[str, str], None]
+
+
+class ChannelResumePolicy:
+    def __init__(self, services: ChannelResumeServices) -> None:
+        self.services = services
+
+    def client_last_event_id(self, handler: Any) -> int | None:
+        try:
+            event_id = parse_channel_event_id(handler.headers.get("Last-Event-ID"))
+            if event_id is not None:
+                return event_id
+        except (AttributeError, TypeError, ValueError) as exc:
+            self.services.log(
+                "WARN",
+                f"channel_mcp_last_event_header_invalid error={type(exc).__name__}: {exc}",
+            )
+        try:
+            params = self.services.query_params(handler)
+            for key in ("lastEventId", "last_event_id", "last_id"):
+                event_id = parse_channel_event_id(self.services.first_param(params, key))
+                if event_id is not None:
+                    return event_id
+        except (AttributeError, TypeError, ValueError) as exc:
+            self.services.log(
+                "WARN",
+                f"channel_mcp_last_event_query_invalid error={type(exc).__name__}: {exc}",
+            )
+        return None
+
+    def session_start_last_id(self, handler: Any) -> int:
+        cursor_last_id = self.services.ensure_cursor()
+        client_last_id = self.client_last_event_id(handler)
+        if client_last_id is None:
+            return cursor_last_id
+        if client_last_id > cursor_last_id:
+            self.services.update_cursor(client_last_id)
+        self.services.log(
+            "INFO",
+            f"channel_mcp_resume client_last_id={client_last_id} "
+            f"cursor_last_id={cursor_last_id}",
+        )
+        return client_last_id
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelDeliveryCursorPorts:
+    response_status: Callable[[Any], int | None]
+    metadata_enabled: Callable[[dict[str, Any] | None], bool]
+    delivery_confirmed: Callable[[Any | None], bool]
+    commit_if_newer: Callable[[int | None], None]
+    log: Callable[[str, str], None]
+
+
+class ChannelDeliveryCursorCommitter:
+    """Commit a pending Channel cursor only after a confirmed HTTP response."""
+
+    def __init__(self, ports: ChannelDeliveryCursorPorts) -> None:
+        self.ports = ports
+
+    @staticmethod
+    def _metadata_int(metadata: dict[str, Any], key: str) -> int | None:
+        try:
+            value = metadata.get(key)
+            if value is None or value == "":
+                return None
+            return max(0, int(value))
+        except (TypeError, ValueError):
+            return None
+
+    def commit(
+        self,
+        body: dict[str, Any],
+        handler: Any | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        if not isinstance(metadata, dict):
+            body_metadata = body.get("metadata")
+            metadata = body_metadata if isinstance(body_metadata, dict) else {}
+        if not metadata:
+            return
+        if handler is not None:
+            status = self.ports.response_status(handler)
+            if status is None or status < 200 or status >= 400:
+                self.ports.log(
+                    "INFO",
+                    "channel_delivery_cursor_deferred "
+                    f"status={status if status is not None else '-'}",
+                )
+                return
+            if (
+                self.ports.metadata_enabled(metadata)
+                and not self.ports.delivery_confirmed(handler)
+            ):
+                reason = str(
+                    getattr(
+                        handler,
+                        "_ciel_runtime_channel_delivery_reason",
+                        "unconfirmed",
+                    )
+                    or "unconfirmed"
+                )
+                self.ports.log(
+                    "INFO",
+                    f"channel_delivery_cursor_deferred reason={reason}",
+                )
+                return
+        cursor = self._metadata_int(
+            metadata,
+            "ciel_runtime_channel_cursor_last_id",
+        )
+        self.ports.commit_if_newer(cursor)