@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/channel_mcp_http_controller.py

@@ -0,0 +1,239 @@
+"""HTTP/SSE controller for the built-in Channel MCP server."""
+
+from __future__ import annotations
+
+import time
+import urllib.parse
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler
+from threading import Condition, Lock
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpSessionStore:
+    states: dict[str, dict[str, Any]]
+    lock: Lock
+
+    def create(self, session: str, last_id: int) -> None:
+        with self.lock:
+            self.states[session] = {
+                "created_at": time.time(),
+                "last_id": last_id,
+                "initialized": False,
+                "outbox": [],
+            }
+
+    def stream_state(self, session: str) -> tuple[int, bool] | None:
+        with self.lock:
+            state = self.states.get(session)
+            if not state:
+                return None
+            return int(state.get("last_id") or 0), bool(state.get("initialized"))
+
+    def set_last_id(self, session: str, last_id: int) -> None:
+        with self.lock:
+            if state := self.states.get(session):
+                state["last_id"] = last_id
+
+    def touch(self, session: str) -> None:
+        with self.lock:
+            if session and session in self.states:
+                self.states[session]["last_seen_at"] = time.time()
+
+    def initialize(self, session: str) -> None:
+        with self.lock:
+            if session and session in self.states:
+                self.states[session]["initialized"] = True
+
+    def remove(self, session: str) -> None:
+        with self.lock:
+            self.states.pop(session, None)
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpStreamServices:
+    new_session_id: Callable[[], str]
+    start_last_id: Callable[[BaseHTTPRequestHandler], int]
+    send_headers: Callable[[BaseHTTPRequestHandler], None]
+    write_event: Callable[..., None]
+    take_outbox: Callable[[str], list[dict[str, Any]]]
+    read_messages: Callable[[int, str | None, str | None, int], list[dict[str, Any]]]
+    project_notifications: Callable[[list[dict[str, Any]], str], tuple[int, list[tuple[int, dict[str, Any]]]]]
+    update_cursor: Callable[[int], None]
+    condition: Condition
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpRpcServices:
+    initialize_response: Callable[[Any, str], dict[str, Any]]
+    tool_schemas: Callable[[], list[dict[str, Any]]]
+    tool_call_response: Callable[[Any, dict[str, Any]], dict[str, Any]]
+    enqueue: Callable[[str, dict[str, Any]], bool]
+    write_json: Callable[..., None]
+    write_accepted: Callable[[BaseHTTPRequestHandler], None]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpHttpController:
+    store: ChannelMcpSessionStore
+    stream: ChannelMcpStreamServices
+    rpc: ChannelMcpRpcServices
+
+    def get(self, handler: BaseHTTPRequestHandler, path: str) -> bool:
+        if path == "/ca/mcp/health":
+            self.rpc.write_json(
+                handler,
+                {
+                    "ok": True,
+                    "name": "ciel-runtime-router",
+                    "streamable_http": "/ca/mcp",
+                    "sse": "/ca/mcp/sse",
+                },
+            )
+            return True
+        if path != "/ca/mcp/sse":
+            return False
+        session = self.stream.new_session_id()
+        last_id = self.stream.start_last_id(handler)
+        self.store.create(session, last_id)
+        self.stream.log("INFO", f"channel_mcp_session_started session={session} last_id={last_id}")
+        started_at = time.time()
+        close_reason = "finished"
+        self.stream.send_headers(handler)
+        self.stream.write_event(
+            handler,
+            "endpoint",
+            f"/ca/mcp/messages?sessionId={urllib.parse.quote(session)}",
+        )
+        try:
+            while True:
+                current = self.store.stream_state(session)
+                if current is None:
+                    close_reason = "session_missing"
+                    return True
+                last_id, initialized = current
+                if outbox := self.stream.take_outbox(session):
+                    for payload in outbox:
+                        self.stream.write_event(handler, "message", payload)
+                    self.stream.log("INFO", f"channel_mcp_rpc_flushed session={session} count={len(outbox)}")
+                    continue
+                if not initialized:
+                    handler.wfile.write(b": waiting-for-initialize\n\n")
+                    handler.wfile.flush()
+                    with self.stream.condition:
+                        self.stream.condition.wait(timeout=1.0)
+                    continue
+                messages = self.stream.read_messages(last_id, None, None, 100)
+                if messages:
+                    delivered_id, events = self.stream.project_notifications(messages, session)
+                    last_id = max(last_id, delivered_id)
+                    for event_id, notification in events:
+                        self.stream.write_event(handler, "message", notification, event_id)
+                        self.stream.log(
+                            "INFO",
+                            f"channel_mcp_notification_written session={session} message_id={event_id}",
+                        )
+                    self.stream.update_cursor(last_id)
+                    self.store.set_last_id(session, last_id)
+                    continue
+                handler.wfile.write(b": keepalive\n\n")
+                handler.wfile.flush()
+                with self.stream.condition:
+                    self.stream.condition.wait(timeout=5.0)
+        except (BrokenPipeError, ConnectionError, ConnectionResetError) as error:
+            close_reason = type(error).__name__
+            return True
+        except Exception as error:
+            close_reason = type(error).__name__
+            self.stream.log(
+                "ERROR",
+                f"channel_mcp_session_failed session={session} error={type(error).__name__}: {error}",
+            )
+            return True
+        finally:
+            age = time.time() - started_at
+            self.stream.log(
+                "INFO",
+                f"channel_mcp_session_closed session={session} reason={close_reason} age={age:.1f}s",
+            )
+            self.store.remove(session)
+
+    def post(
+        self,
+        handler: BaseHTTPRequestHandler,
+        path: str,
+        body: dict[str, Any],
+    ) -> bool:
+        if path == "/ca/mcp":
+            response = self._rpc_response(body)
+            if response is None:
+                self.rpc.write_accepted(handler)
+            else:
+                self.rpc.write_json(handler, response)
+            self.rpc.log(
+                "INFO",
+                "channel_mcp_streamable_http method=%s request_id=%s"
+                % (str(body.get("method") or ""), body.get("id")),
+            )
+            return True
+        if path != "/ca/mcp/messages":
+            return False
+        query = urllib.parse.parse_qs(
+            urllib.parse.urlparse(handler.path).query,
+            keep_blank_values=True,
+        )
+        session = (query.get("sessionId") or query.get("session") or [""])[0]
+        self.store.touch(session)
+        method = str(body.get("method") or "")
+        request_id = body.get("id")
+        if method == "initialize":
+            self.store.initialize(session)
+        response = self._rpc_response(body)
+        if method == "initialize":
+            params = body.get("params") if isinstance(body.get("params"), dict) else {}
+            protocol = str(params.get("protocolVersion") or "2024-11-05")
+            self.rpc.log("INFO", f"channel_mcp_initialized session={session or '-'} protocol={protocol}")
+        if response is not None:
+            if not self.rpc.enqueue(session, response):
+                self.rpc.log("WARN", f"channel_mcp_rpc_enqueue_failed session={session or '-'} method={method}")
+                self.rpc.write_json(
+                    handler,
+                    {
+                        "jsonrpc": "2.0",
+                        "id": request_id,
+                        "error": {"code": -32000, "message": "MCP SSE session is not connected"},
+                    },
+                    404,
+                )
+                return True
+            self.rpc.log(
+                "INFO",
+                f"channel_mcp_rpc_queued session={session or '-'} method={method} request_id={request_id}",
+            )
+        self.rpc.write_accepted(handler)
+        return True
+
+    def _rpc_response(self, body: dict[str, Any]) -> dict[str, Any] | None:
+        method = str(body.get("method") or "")
+        request_id = body.get("id")
+        if method == "initialize":
+            params = body.get("params") if isinstance(body.get("params"), dict) else {}
+            protocol = str(params.get("protocolVersion") or "2024-11-05")
+            return self.rpc.initialize_response(request_id, protocol)
+        if method == "tools/list":
+            return {
+                "jsonrpc": "2.0",
+                "id": request_id,
+                "result": {"tools": self.rpc.tool_schemas()},
+            }
+        if method == "tools/call":
+            params = body.get("params") if isinstance(body.get("params"), dict) else {}
+            return self.rpc.tool_call_response(request_id, params)
+        if method == "ping":
+            return {"jsonrpc": "2.0", "id": request_id, "result": {}}
+        if request_id is not None:
+            return {"jsonrpc": "2.0", "id": request_id, "result": {}}
+        return None

package/ciel_runtime_support/channel_mcp_ownership.py

@@ -0,0 +1,148 @@
+"""Ownership repository and lifecycle for MCP channel notification streams."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+class ChannelProxyOwnershipRepository:
+    def __init__(
+        self,
+        proxy_config: Path,
+        disable_notifications: Callable[[dict[str, Any]], bool],
+        log: Callable[[str, str], None],
+    ) -> None:
+        self.proxy_config = proxy_config
+        self.disable_notifications = disable_notifications
+        self.log = log
+
+    def owned_names(self) -> set[str]:
+        try:
+            data = json.loads(self.proxy_config.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return set()
+        except (OSError, UnicodeError, json.JSONDecodeError, TypeError) as exc:
+            self.log(
+                "WARN",
+                f"proxy_owned_channel_config_read_failed path={self.proxy_config} "
+                f"error={type(exc).__name__}: {exc}",
+            )
+            return set()
+        servers = data.get("mcpServers") if isinstance(data, dict) else None
+        if not isinstance(servers, dict):
+            return set()
+        owned: set[str] = set()
+        for name, entry in servers.items():
+            if not isinstance(entry, dict) or not isinstance(entry.get("args"), list):
+                continue
+            arguments = [str(argument) for argument in entry["args"]]
+            if "mcp-proxy" not in arguments or "--server-name" not in arguments:
+                continue
+            try:
+                wrapped_name = arguments[arguments.index("--server-name") + 1].strip()
+            except IndexError:
+                wrapped_name = str(name).strip()
+            if self.server_config_disables_notifications(arguments):
+                continue
+            if wrapped_name:
+                owned.add(wrapped_name)
+        return owned
+
+    def server_config_disables_notifications(self, arguments: list[str]) -> bool:
+        try:
+            path = Path(arguments[arguments.index("--server-config") + 1])
+        except (ValueError, IndexError):
+            return False
+        try:
+            server = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeError, json.JSONDecodeError, TypeError) as exc:
+            self.log(
+                "WARN",
+                f"proxy_server_config_read_failed path={path} "
+                f"error={type(exc).__name__}: {exc}",
+            )
+            return False
+        return (
+            self.disable_notifications(server) if isinstance(server, dict) else False
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelRouterLifecyclePorts:
+    delivery_enabled: Callable[..., bool]
+    launch_specs: Callable[[dict[str, Any], list[str]], list[str]]
+    server_names: Callable[[Iterable[str]], list[str]]
+    owned_names: Callable[[], set[str]]
+    public_name: Callable[[str], str]
+    ensure_probe: Callable[..., bool]
+    source_paths: Callable[[Iterable[str]], list[Path]]
+    auto_start: Callable[..., list[dict[str, Any]]]
+    log: Callable[[str, str], None]
+
+
+class ChannelRouterLifecycle:
+    def __init__(
+        self,
+        native_router_names: frozenset[str],
+        ports: ChannelRouterLifecyclePorts,
+    ) -> None:
+        self.native_router_names = native_router_names
+        self.ports = ports
+
+    def managed_names(self, config: dict[str, Any]) -> list[str]:
+        names = self.ports.server_names(self.ports.launch_specs(config, []))
+        names = [name for name in names if name.lower() not in self.native_router_names]
+        owned = self.ports.owned_names()
+        if not owned:
+            return names
+        owned_public = {self.ports.public_name(name) for name in owned}
+        kept = [
+            name for name in names if self.ports.public_name(name) not in owned_public
+        ]
+        if len(kept) != len(names):
+            dropped = sorted(set(names) - set(kept))
+            self.ports.log(
+                "INFO",
+                "router_channel_sse_skipped_proxy_owned "
+                f"servers={','.join(dropped) or '-'}",
+            )
+        return kept
+
+    def start(self, config: dict[str, Any]) -> list[dict[str, Any]]:
+        if not self.ports.delivery_enabled(True, [], config):
+            return []
+        names = self.managed_names(config)
+        if not names:
+            self.ports.log(
+                "INFO", "router_channel_sse_skipped reason=no_external_channel_specs"
+            )
+            return []
+        source_paths: list[Path] = []
+        try:
+            self.ports.ensure_probe(config, [])
+            source_paths = self.ports.source_paths(
+                [f"server:{name}" for name in names]
+            )
+        except Exception as exc:
+            self.ports.log(
+                "WARN",
+                f"router_channel_probe_cache_failed "
+                f"error={type(exc).__name__}: {exc}",
+            )
+        started = self.ports.auto_start(
+            [],
+            extra_config_paths=source_paths,
+            allowed_server_names=list(names),
+        )
+        self.ports.log(
+            "INFO",
+            f"router_channel_sse_started count={len(started)} servers="
+            + (
+                ",".join(str(item.get("name") or "") for item in started) or "-"
+            ),
+        )
+        return started

package/ciel_runtime_support/channel_mcp_tools.py

@@ -0,0 +1,240 @@
+"""Built-in channel MCP tool catalog and application service."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpToolServices:
+    queue_compact: Callable[[str, str], dict[str, Any]]
+    append_message: Callable[[dict[str, Any]], dict[str, Any]]
+    store_file_path: Callable[[Any, str | None, str | None], dict[str, Any]]
+    store_file_upload: Callable[[dict[str, Any]], dict[str, Any]]
+    file_message_text: Callable[[str, list[dict[str, Any]]], str]
+    handle_llm_options: Callable[[str, str], tuple[list[str], bool]]
+
+
+def channel_mcp_tool_schemas() -> list[dict[str, Any]]:
+    return [
+        {
+            "name": "compact_session",
+            "description": (
+                "Queue Claude Code's /compact slash command for the active Ciel Runtime-launched session. "
+                "Use this when the conversation context is too large and the session should compact itself."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "reason": {
+                        "type": "string",
+                        "description": "Optional short reason shown in Ciel Runtime logs.",
+                    },
+                },
+            },
+        },
+        {
+            "name": "send_message",
+            "description": (
+                "Send a reply or status message to a Ciel Runtime channel. "
+                "Use this to answer messages delivered through the Ciel Runtime channel inbox, "
+                "including /ca/web/chat browser sessions."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "channel": {"type": "string", "description": "Destination channel id from the incoming message."},
+                    "message": {"type": "string", "description": "Message body to send."},
+                    "recipients": {
+                        "description": "Recipient id, 'all', or an array of recipients. Use 'web' for /ca/web/chat replies."
+                    },
+                    "thread_id": {"type": "string", "description": "Thread/conversation id to continue."},
+                    "parent_id": {"description": "Optional parent message id."},
+                    "delivery": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Delivery targets. Use ['web'] for browser-only replies.",
+                    },
+                    "kind": {"type": "string", "description": "Optional message kind, for example 'reply' or 'status'."},
+                },
+                "required": ["channel", "message"],
+            },
+        },
+        {
+            "name": "send_file",
+            "description": (
+                "Send a file attachment to a Ciel Runtime channel. "
+                "Use this to return files to /ca/web/chat browser sessions. "
+                "Provide either path for an existing local file, or content with encoding='text' or encoding='base64'."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "channel": {"type": "string", "description": "Destination channel id from the incoming message."},
+                    "path": {"type": "string", "description": "Optional local file path to attach."},
+                    "content": {
+                        "type": "string",
+                        "description": "Optional inline file content when path is not used.",
+                    },
+                    "encoding": {"type": "string", "description": "Inline content encoding: text or base64."},
+                    "name": {
+                        "type": "string",
+                        "description": "Display filename. Defaults to the source path basename or file.txt.",
+                    },
+                    "content_type": {"type": "string", "description": "Optional MIME type."},
+                    "message": {"type": "string", "description": "Optional message body to show with the file link."},
+                    "recipients": {
+                        "description": "Recipient id, 'all', or an array of recipients. Use 'web' for /ca/web/chat replies."
+                    },
+                    "thread_id": {"type": "string", "description": "Thread/conversation id to continue."},
+                    "parent_id": {"description": "Optional parent message id."},
+                    "delivery": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Delivery targets. Use ['web'] for browser-only replies.",
+                    },
+                },
+                "required": ["channel"],
+            },
+        },
+        {
+            "name": "llm_options",
+            "description": (
+                "Show, apply, or restore ciel-runtime live LLM option presets for the current routed session. "
+                "Use action='list' to show keyboard-selectable slash commands, action='apply' with preset, "
+                "or action='restore' to return to the captured original options."
+            ),
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "action": {"type": "string", "description": "One of status, list, apply, or restore."},
+                    "preset": {
+                        "type": "string",
+                        "description": (
+                            "Preset id or alias when action is apply, for example balanced, long-context-256k, "
+                            "long-context-300k, long-context-512k, or million-context-1m."
+                        ),
+                    },
+                },
+            },
+        },
+    ]
+
+
+def channel_mcp_tool_response(request_id: Any, text: str, is_error: bool = False) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "result": {"content": [{"type": "text", "text": text}], "isError": bool(is_error)},
+    }
+
+
+def dispatch_channel_mcp_tool(
+    request_id: Any,
+    params: dict[str, Any],
+    services: ChannelMcpToolServices,
+) -> dict[str, Any]:
+    name = str(params.get("name") or "")
+    args = params.get("arguments") if isinstance(params.get("arguments"), dict) else {}
+    if name == "compact_session":
+        request = services.queue_compact("ciel-runtime-router-tool", str(args.get("reason") or ""))
+        return _json_response(
+            request_id,
+            {
+                "ok": True,
+                "queued": True,
+                "command": request.get("command"),
+                "request_id": request.get("id"),
+                "expires_at": request.get("expires_at"),
+            },
+        )
+    if name == "send_message":
+        return _send_message(request_id, args, services)
+    if name == "send_file":
+        return _send_file(request_id, args, services)
+    if name == "llm_options":
+        lines, changed = services.handle_llm_options(
+            str(args.get("action") or "status"),
+            str(args.get("preset") or ""),
+        )
+        return _json_response(request_id, {"ok": True, "changed": changed, "lines": lines})
+    return channel_mcp_tool_response(request_id, f"Unknown ciel-runtime-router tool: {name}", True)
+
+
+def _send_message(
+    request_id: Any,
+    args: dict[str, Any],
+    services: ChannelMcpToolServices,
+) -> dict[str, Any]:
+    channel = str(args.get("channel") or "").strip()
+    message = str(args.get("message") or args.get("text") or "").strip()
+    if not channel or not message:
+        return channel_mcp_tool_response(request_id, "send_message requires channel and message.", True)
+    saved = services.append_message(_message_payload(args, channel, message, "reply"))
+    return _json_response(request_id, {"ok": True, "message": saved})
+
+
+def _send_file(
+    request_id: Any,
+    args: dict[str, Any],
+    services: ChannelMcpToolServices,
+) -> dict[str, Any]:
+    channel = str(args.get("channel") or "").strip()
+    if not channel:
+        return channel_mcp_tool_response(request_id, "send_file requires channel.", True)
+    try:
+        upload = _store_file(args, services)
+    except (FileNotFoundError, OverflowError, ValueError) as exc:
+        return channel_mcp_tool_response(request_id, str(exc), True)
+    uploads = [upload]
+    message = services.file_message_text(str(args.get("message") or ""), uploads)
+    payload = _message_payload(args, channel, message, "file")
+    payload["meta"] = {"attachments": uploads, **payload["meta"]}
+    saved = services.append_message(payload)
+    return _json_response(request_id, {"ok": True, "file": upload, "message": saved})
+
+
+def _store_file(args: dict[str, Any], services: ChannelMcpToolServices) -> dict[str, Any]:
+    if args.get("path"):
+        return services.store_file_path(
+            args.get("path"),
+            str(args.get("name") or "").strip() or None,
+            str(args.get("content_type") or args.get("mime_type") or "").strip() or None,
+        )
+    return services.store_file_upload(
+        {
+            "name": str(args.get("name") or "file.txt"),
+            "encoding": str(args.get("encoding") or "text"),
+            "content": args.get("content", ""),
+            "content_type": str(args.get("content_type") or args.get("mime_type") or "text/plain"),
+        }
+    )
+
+
+def _message_payload(
+    args: dict[str, Any],
+    channel: str,
+    message: str,
+    default_kind: str,
+) -> dict[str, Any]:
+    meta = args.get("meta") if isinstance(args.get("meta"), dict) else {}
+    return {
+        "channel": channel,
+        "sender_id": args.get("sender_id") or "claude-code",
+        "recipients": args.get("recipients", args.get("recipient_id", "web")),
+        "thread_id": args.get("thread_id"),
+        "parent_id": args.get("parent_id"),
+        "kind": args.get("kind") or default_kind,
+        "message": message,
+        "delivery": args.get("delivery", ["web"]),
+        "meta": {"source": "ciel-runtime-router-tool", **meta},
+    }
+
+
+def _json_response(request_id: Any, payload: dict[str, Any]) -> dict[str, Any]:
+    return channel_mcp_tool_response(
+        request_id,
+        json.dumps(payload, ensure_ascii=False, separators=(",", ":")),
+    )