@oneciel-ai/ciel-runtime 0.2.2 → 0.2.3

package/ciel_runtime_support/channel_delivery_context.py

@@ -0,0 +1,332 @@
+"""Channel tool-context and durable LLM delivery cursor bounded context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler
+from pathlib import Path
+from typing import Any, Callable, Protocol
+
+from .channel_cursor_repository import (
+    ChannelCursorRepository,
+    ChannelCursorStatePolicy,
+)
+from .channel_cursor_service import (
+    ChannelDeliveryCursorCommitter,
+    ChannelDeliveryCursorPorts,
+)
+from .channel_tool_context import (
+    ChannelToolContextPolicy,
+    ChannelToolContextPorts,
+    ChannelToolContextRepository,
+    ChannelToolContextService,
+)
+
+
+class LockPort(Protocol):
+    def __enter__(self) -> object: ...
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: object | None,
+    ) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelToolContextFactoryPorts:
+    contexts: dict[str, dict[str, Any]]
+    lock: LockPort
+    context_limit: int
+    max_inject: int
+    prompt_limit: int
+    content_to_text: Callable[[Any], str]
+    truncate: Callable[..., str]
+    now: Callable[[], float]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelLlmCursorPorts:
+    repository: Callable[[Path], ChannelCursorRepository]
+    cursor_path: Path
+    clear_floor_path: Path
+    lock: LockPort
+    cache_read: Callable[[], int | None]
+    cache_write: Callable[[int | None], None]
+    scan_max_id: Callable[[], int]
+    now: Callable[[], float]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelLaunchCursorPorts:
+    recent_seconds: Callable[[], float]
+    scan_max_before_epoch: Callable[[float], int]
+    write_launch_guard: Callable[[int], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelDeliveryCommitPorts:
+    response_status: Callable[[Any], int | None]
+    metadata_enabled: Callable[[dict[str, Any] | None], bool]
+    delivery_confirmed: Callable[[Any], bool]
+    read_cursor: Callable[[], int]
+    write_cursor: Callable[[int], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelDeliveryContext:
+    tools: ChannelToolContextFactoryPorts
+    cursor: ChannelLlmCursorPorts
+    launch: ChannelLaunchCursorPorts
+    commit: ChannelDeliveryCommitPorts
+
+    def tool_context_service(self) -> ChannelToolContextService:
+        ports = self.tools
+        return ChannelToolContextService(
+            repository=ChannelToolContextRepository(
+                contexts=ports.contexts,
+                lock=ports.lock,
+                limit=ports.context_limit,
+            ),
+            policy=ChannelToolContextPolicy(
+                max_inject=ports.max_inject,
+                prompt_limit=ports.prompt_limit,
+            ),
+            ports=ChannelToolContextPorts(
+                content_to_text=ports.content_to_text,
+                truncate=ports.truncate,
+                now=ports.now,
+                log=ports.log,
+            ),
+        )
+
+    def injected_prompt_text(self, body: dict[str, Any]) -> str:
+        return self.tool_context_service().prompt_text(body)
+
+    def remember_injected_tool_use(
+        self,
+        source_body: dict[str, Any] | None,
+        tool_use_id: str,
+        tool_name: str,
+        tool_input: Any,
+    ) -> None:
+        self.tool_context_service().remember(
+            source_body, tool_use_id, tool_name, tool_input
+        )
+
+    def remember_injected_tool_uses(
+        self, source_body: dict[str, Any] | None, message: dict[str, Any]
+    ) -> None:
+        self.tool_context_service().remember_message(source_body, message)
+
+    def take_tool_result_contexts(
+        self, body: dict[str, Any]
+    ) -> list[tuple[str, dict[str, Any]]]:
+        return self.tool_context_service().repository.take_for_body(
+            body, self.tools.max_inject
+        )
+
+    def body_with_tool_result_context(
+        self, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self.tool_context_service().inject_followup(body)
+
+    def write_cursor(self, last_id: int) -> None:
+        self.cursor.repository(self.cursor.cursor_path).write(last_id)
+
+    def read_cursor(self) -> int:
+        resolution = ChannelCursorStatePolicy.resolve_read(
+            self.cursor.repository(self.cursor.cursor_path).read(),
+            self.cursor.cache_read(),
+            self.cursor.scan_max_id,
+        )
+        self.cursor.cache_write(resolution.value)
+        if resolution.rolled_back:
+            self.cursor.log(
+                "WARN",
+                "channel_llm_cursor_queue_generation_reset "
+                f"recovered_cursor={resolution.value}",
+            )
+        if resolution.persist:
+            self.write_cursor(resolution.value)
+        return resolution.value
+
+    def read_clear_floor(self) -> int:
+        return self.cursor.repository(self.cursor.clear_floor_path).read() or 0
+
+    def write_clear_floor(self, last_id: int) -> None:
+        self.cursor.repository(self.cursor.clear_floor_path).write(
+            last_id, metadata={"updated_at": self.cursor.now()}
+        )
+
+    def clamp_to_clear_floor(self, recovered: int) -> int:
+        clear_floor = self.read_clear_floor()
+        if clear_floor > 0 and recovered < clear_floor:
+            self.cursor.log(
+                "INFO",
+                "channel_stdin_proxy_recovery_clamped "
+                f"recovered_cursor={recovered} clear_floor={clear_floor}",
+            )
+            return clear_floor
+        return recovered
+
+    def reset_cursor(self, last_id: int | None = None) -> int:
+        with self.cursor.lock:
+            target = max(
+                0,
+                int(
+                    last_id
+                    if last_id is not None
+                    else self.cursor.scan_max_id()
+                ),
+            )
+            self.cursor.cache_write(target)
+            self.write_cursor(target)
+            return target
+
+    def ensure_cursor_initialized(self) -> int:
+        with self.cursor.lock:
+            return self.read_cursor()
+
+    def prepare_for_launch(self) -> int:
+        current = self.ensure_cursor_initialized()
+        recent_seconds = self.launch.recent_seconds()
+        if recent_seconds <= 0:
+            target = self.cursor.scan_max_id()
+        else:
+            target = self.launch.scan_max_before_epoch(
+                self.cursor.now() - recent_seconds
+            )
+        # The stale cutoff is a durable safety boundary, not merely a startup
+        # cursor optimization.  Transcript recovery may legitimately rewind a
+        # cursor for a recently queued command that was not completed before a
+        # crash, but it must never reopen commands older than this launch's
+        # replay window.
+        self.write_clear_floor(max(self.read_clear_floor(), target))
+        last_id = self.reset_cursor(max(current, target))
+        self.launch.write_launch_guard(last_id)
+        self.cursor.log(
+            "INFO",
+            "channel_llm_cursor_fast_forward_on_launch "
+            f"last_id={last_id} previous_cursor={current} "
+            f"recent_seconds={recent_seconds:g}",
+        )
+        return last_id
+
+    def commit_if_newer(self, last_id: int | None) -> None:
+        with self.cursor.lock:
+            current = self.commit.read_cursor()
+            target = ChannelCursorStatePolicy.newer(last_id, current)
+            if target is None:
+                return
+            self.cursor.cache_write(target)
+            try:
+                self.commit.write_cursor(target)
+            except Exception as exc:
+                self.cursor.log(
+                    "WARN",
+                    "channel_llm_cursor_write_failed "
+                    f"error={type(exc).__name__}: {exc}",
+                )
+
+    def commit_pending(
+        self,
+        body: dict[str, Any],
+        handler: BaseHTTPRequestHandler | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        ChannelDeliveryCursorCommitter(
+            ChannelDeliveryCursorPorts(
+                response_status=self.commit.response_status,
+                metadata_enabled=self.commit.metadata_enabled,
+                delivery_confirmed=self.commit.delivery_confirmed,
+                commit_if_newer=self.commit_if_newer,
+                log=self.cursor.log,
+            )
+        ).commit(body, handler, metadata)
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelDeliveryCompatibilityApi:
+    context: Callable[[], ChannelDeliveryContext]
+
+    def tool_context_service(self) -> ChannelToolContextService:
+        return self.context().tool_context_service()
+
+    def injected_prompt_text(self, body: dict[str, Any]) -> str:
+        return self.context().injected_prompt_text(body)
+
+    def remember_injected_tool_use(
+        self,
+        source_body: dict[str, Any] | None,
+        tool_use_id: str,
+        tool_name: str,
+        tool_input: Any,
+    ) -> None:
+        self.context().remember_injected_tool_use(
+            source_body, tool_use_id, tool_name, tool_input
+        )
+
+    def remember_injected_tool_uses(
+        self, source_body: dict[str, Any] | None, message: dict[str, Any]
+    ) -> None:
+        self.context().remember_injected_tool_uses(source_body, message)
+
+    def take_tool_result_contexts(
+        self, body: dict[str, Any]
+    ) -> list[tuple[str, dict[str, Any]]]:
+        return self.context().take_tool_result_contexts(body)
+
+    def body_with_tool_result_context(
+        self, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self.context().body_with_tool_result_context(body)
+
+    def write_cursor(self, last_id: int) -> None:
+        self.context().write_cursor(last_id)
+
+    def read_cursor(self) -> int:
+        return self.context().read_cursor()
+
+    def read_clear_floor(self) -> int:
+        return self.context().read_clear_floor()
+
+    def write_clear_floor(self, last_id: int) -> None:
+        self.context().write_clear_floor(last_id)
+
+    def clamp_to_clear_floor(self, recovered: int) -> int:
+        return self.context().clamp_to_clear_floor(recovered)
+
+    def reset_cursor(self, last_id: int | None = None) -> int:
+        return self.context().reset_cursor(last_id)
+
+    def ensure_cursor_initialized(self) -> int:
+        return self.context().ensure_cursor_initialized()
+
+    def prepare_for_launch(self) -> int:
+        return self.context().prepare_for_launch()
+
+    def commit_if_newer(self, last_id: int | None) -> None:
+        self.context().commit_if_newer(last_id)
+
+    def commit_pending(
+        self,
+        body: dict[str, Any],
+        handler: BaseHTTPRequestHandler | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self.context().commit_pending(body, handler, metadata)
+
+
+__all__ = [
+    "ChannelDeliveryCommitPorts",
+    "ChannelDeliveryCompatibilityApi",
+    "ChannelDeliveryContext",
+    "ChannelLaunchCursorPorts",
+    "ChannelLlmCursorPorts",
+    "ChannelToolContextFactoryPorts",
+    "LockPort",
+]

package/ciel_runtime_support/channel_mcp_context.py

@@ -0,0 +1,313 @@
+"""Built-in channel MCP server bounded context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+from .channel_cursor_repository import ChannelCursorRepository
+from .channel_cursor_service import (
+    ChannelCursorService,
+    ChannelCursorServices,
+    ChannelResumePolicy,
+    ChannelResumeServices,
+)
+from .channel_mcp_http_controller import (
+    ChannelMcpHttpController,
+    ChannelMcpRpcServices,
+    ChannelMcpSessionStore,
+    ChannelMcpStreamServices,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpRuntimePorts:
+    version: str
+    process_id: Callable[[], int]
+    timestamp_ns: Callable[[], int]
+    condition: Any
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpStatePorts:
+    sessions: dict[str, dict[str, Any]]
+    session_lock: Any
+    cursor_lock: Any
+    cursor_path: Path
+    cached_cursor: Callable[[], int | None]
+    cache_cursor: Callable[[int], None]
+    scan_tail: Callable[[], int]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpProjectionPorts:
+    capabilities: Callable[[], dict[str, Any]]
+    notifications: Callable[..., list[tuple[int, dict[str, Any]]]]
+    read_messages: Callable[..., list[dict[str, Any]]]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpRpcPorts:
+    tool_schemas: Callable[[], list[dict[str, Any]]]
+    tool_call_response: Callable[[Any, dict[str, Any]], dict[str, Any]]
+    write_json: Callable[..., None]
+    write_accepted: Callable[..., None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpResumePorts:
+    query_params: Callable[..., dict[str, list[str]]]
+    first_param: Callable[..., str]
+    ensure_cursor: Callable[[], int]
+    update_cursor: Callable[[int], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpContext:
+    runtime: ChannelMcpRuntimePorts
+    state: ChannelMcpStatePorts
+    projection: ChannelMcpProjectionPorts
+    rpc: ChannelMcpRpcPorts
+    resume: ChannelMcpResumePorts
+    cursor_repository: Callable[[Path], ChannelCursorRepository]
+
+    def new_session_id(self) -> str:
+        return f"s{self.runtime.process_id()}-{self.runtime.timestamp_ns()}"
+
+    @staticmethod
+    def write_sse_event(
+        handler: BaseHTTPRequestHandler,
+        event: str,
+        data: Any,
+        event_id: int | None = None,
+    ) -> None:
+        if event_id is not None:
+            handler.wfile.write(f"id: {event_id}\n".encode("utf-8"))
+        handler.wfile.write(f"event: {event}\n".encode("utf-8"))
+        payload = (
+            data
+            if isinstance(data, str)
+            else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
+        )
+        for line in payload.splitlines() or [""]:
+            handler.wfile.write(f"data: {line}\n".encode("utf-8"))
+        handler.wfile.write(b"\n")
+        handler.wfile.flush()
+
+    @staticmethod
+    def send_sse_headers(handler: BaseHTTPRequestHandler) -> None:
+        handler.send_response(200)
+        handler.send_header("content-type", "text/event-stream")
+        handler.send_header("cache-control", "no-cache, no-transform")
+        handler.send_header("connection", "keep-alive")
+        handler.send_header("x-accel-buffering", "no")
+        handler.end_headers()
+
+    def enqueue(self, session: str, payload: dict[str, Any]) -> bool:
+        if not session:
+            return False
+        with self.state.session_lock:
+            state = self.state.sessions.get(session)
+            if not state:
+                return False
+            outbox = state.setdefault("outbox", [])
+            if isinstance(outbox, list):
+                outbox.append(payload)
+            else:
+                state["outbox"] = [payload]
+        with self.runtime.condition:
+            self.runtime.condition.notify_all()
+        return True
+
+    def take_outbox(self, session: str) -> list[dict[str, Any]]:
+        with self.state.session_lock:
+            state = self.state.sessions.get(session)
+            if not state:
+                return []
+            outbox = state.get("outbox")
+            if not isinstance(outbox, list) or not outbox:
+                return []
+            state["outbox"] = []
+            return [item for item in outbox if isinstance(item, dict)]
+
+    def initialize_response(self, request_id: Any, protocol: str) -> dict[str, Any]:
+        del protocol
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": self.projection.capabilities(),
+                "serverInfo": {
+                    "name": "ciel-runtime-router",
+                    "version": self.runtime.version,
+                },
+            },
+        }
+
+    def cursor_service(self) -> ChannelCursorService:
+        return ChannelCursorService(
+            ChannelCursorServices(
+                repository=self.cursor_repository(self.state.cursor_path),
+                lock=self.state.cursor_lock,
+                cached=self.state.cached_cursor,
+                cache=self.state.cache_cursor,
+                scan_tail=self.state.scan_tail,
+            )
+        )
+
+    def write_cursor(self, last_id: int) -> None:
+        self.cursor_repository(self.state.cursor_path).write(last_id)
+
+    def read_cursor(self) -> int:
+        return self.cursor_service().read_locked()
+
+    def ensure_cursor(self) -> int:
+        return self.cursor_service().ensure_initialized()
+
+    def update_cursor(self, last_id: int) -> None:
+        self.cursor_service().update(last_id)
+
+    def resume_policy(self) -> ChannelResumePolicy:
+        return ChannelResumePolicy(
+            ChannelResumeServices(
+                query_params=self.resume.query_params,
+                first_param=self.resume.first_param,
+                ensure_cursor=self.resume.ensure_cursor,
+                update_cursor=self.resume.update_cursor,
+                log=self.runtime.log,
+            )
+        )
+
+    def client_last_event_id(
+        self, handler: BaseHTTPRequestHandler
+    ) -> int | None:
+        return self.resume_policy().client_last_event_id(handler)
+
+    def session_start_last_id(self, handler: BaseHTTPRequestHandler) -> int:
+        return self.resume_policy().session_start_last_id(handler)
+
+    def controller(self) -> ChannelMcpHttpController:
+        return ChannelMcpHttpController(
+            store=ChannelMcpSessionStore(
+                self.state.sessions, self.state.session_lock
+            ),
+            stream=ChannelMcpStreamServices(
+                new_session_id=self.new_session_id,
+                start_last_id=self.session_start_last_id,
+                send_headers=self.send_sse_headers,
+                write_event=self.write_sse_event,
+                take_outbox=self.take_outbox,
+                read_messages=self.projection.read_messages,
+                project_notifications=self.projection.notifications,
+                update_cursor=self.update_cursor,
+                condition=self.runtime.condition,
+                log=self.runtime.log,
+            ),
+            rpc=ChannelMcpRpcServices(
+                initialize_response=self.initialize_response,
+                tool_schemas=self.rpc.tool_schemas,
+                tool_call_response=self.rpc.tool_call_response,
+                enqueue=self.enqueue,
+                write_json=self.rpc.write_json,
+                write_accepted=self.rpc.write_accepted,
+                log=self.runtime.log,
+            ),
+        )
+
+    def get(self, handler: BaseHTTPRequestHandler, path: str) -> bool:
+        return self.controller().get(handler, path)
+
+    def post(
+        self,
+        handler: BaseHTTPRequestHandler,
+        path: str,
+        body: dict[str, Any],
+    ) -> bool:
+        return self.controller().post(handler, path, body)
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpCompatibilityApi:
+    context: Callable[[], ChannelMcpContext]
+
+    def new_session_id(self) -> str:
+        return self.context().new_session_id()
+
+    def write_sse_event(
+        self,
+        handler: BaseHTTPRequestHandler,
+        event: str,
+        data: Any,
+        event_id: int | None = None,
+    ) -> None:
+        self.context().write_sse_event(handler, event, data, event_id)
+
+    def send_sse_headers(self, handler: BaseHTTPRequestHandler) -> None:
+        self.context().send_sse_headers(handler)
+
+    def enqueue(self, session: str, payload: dict[str, Any]) -> bool:
+        return self.context().enqueue(session, payload)
+
+    def take_outbox(self, session: str) -> list[dict[str, Any]]:
+        return self.context().take_outbox(session)
+
+    def initialize_response(
+        self, request_id: Any, protocol: str
+    ) -> dict[str, Any]:
+        return self.context().initialize_response(request_id, protocol)
+
+    def cursor_service(self) -> ChannelCursorService:
+        return self.context().cursor_service()
+
+    def write_cursor(self, last_id: int) -> None:
+        self.context().write_cursor(last_id)
+
+    def read_cursor(self) -> int:
+        return self.context().read_cursor()
+
+    def ensure_cursor(self) -> int:
+        return self.context().ensure_cursor()
+
+    def update_cursor(self, last_id: int) -> None:
+        self.context().update_cursor(last_id)
+
+    def resume_policy(self) -> ChannelResumePolicy:
+        return self.context().resume_policy()
+
+    def client_last_event_id(
+        self, handler: BaseHTTPRequestHandler
+    ) -> int | None:
+        return self.context().client_last_event_id(handler)
+
+    def session_start_last_id(self, handler: BaseHTTPRequestHandler) -> int:
+        return self.context().session_start_last_id(handler)
+
+    def controller(self) -> ChannelMcpHttpController:
+        return self.context().controller()
+
+    def get(self, handler: BaseHTTPRequestHandler, path: str) -> bool:
+        return self.context().get(handler, path)
+
+    def post(
+        self,
+        handler: BaseHTTPRequestHandler,
+        path: str,
+        body: dict[str, Any],
+    ) -> bool:
+        return self.context().post(handler, path, body)
+
+
+__all__ = [
+    "ChannelMcpCompatibilityApi",
+    "ChannelMcpContext",
+    "ChannelMcpProjectionPorts",
+    "ChannelMcpResumePorts",
+    "ChannelMcpRpcPorts",
+    "ChannelMcpRuntimePorts",
+    "ChannelMcpStatePorts",
+]

package/ciel_runtime_support/channel_mcp_discovery.py

@@ -184,3 +184,50 @@ class ChannelMcpDiscoveryService:
                 seen.add(key)
                 unique.append(path)
         return unique
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpDiscoveryCompatibilityApi:
+    service: Callable[[], ChannelMcpDiscoveryService]
+
+    def runtime_headers(self, server: dict[str, Any]) -> dict[str, str]:
+        return self.service().runtime_headers(server)
+
+    def servers_from_mapping(self, mapping: Any) -> list[dict[str, Any]]:
+        return self.service().servers_from_mapping(mapping)
+
+    def external_names(
+        self,
+        passthrough: list[str] | None = None,
+        cwd: Path | None = None,
+        home: Path | None = None,
+        extra_config_paths: list[Path | str] | None = None,
+    ) -> list[str]:
+        return self.service().external_names(
+            passthrough, cwd, home, extra_config_paths
+        )
+
+    def auto_start(
+        self,
+        passthrough: list[str] | None = None,
+        cwd: Path | None = None,
+        home: Path | None = None,
+        extra_config_paths: list[Path | str] | None = None,
+        allowed_server_names: Iterable[str] | None = None,
+        include_default_paths: bool = True,
+    ) -> list[dict[str, Any]]:
+        return self.service().auto_start(
+            passthrough,
+            cwd,
+            home,
+            extra_config_paths,
+            allowed_server_names,
+            include_default_paths,
+        )
+
+
+__all__ = [
+    "ChannelMcpDiscoveryCompatibilityApi",
+    "ChannelMcpDiscoveryPorts",
+    "ChannelMcpDiscoveryService",
+]