@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/channel_injection.py

@@ -0,0 +1,115 @@
+"""Runtime-neutral contracts for injecting channel prompts into interactive CLIs.
+
+This module owns runtime input policy and terminal delivery orchestration. It
+does not know about SSE, MCP, cursors, transcripts, or subprocess lifecycle.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Protocol
+
+
+class InputTransport(Protocol):
+    """Input port implemented by PTY and Windows Console adapters."""
+
+    def write(self, data: bytes) -> None: ...
+
+    def wait_until_input_consumed(self, timeout_seconds: float = 2.0) -> bool: ...
+
+
+@dataclass(frozen=True)
+class RuntimeInjectionPolicy:
+    """Runtime interaction semantics independent of the host platform."""
+
+    runtime: str
+    clear_input: bytes
+    submit_input: bytes
+    submit_delay_seconds: float
+    submit_attempts: int = 1
+    confirm_submission: bool = False
+    bracketed_paste: bool = False
+    input_drain_timeout_seconds: float = 2.0
+
+    def __post_init__(self) -> None:
+        if not self.runtime.strip():
+            raise ValueError("runtime is required")
+        if not self.submit_input:
+            raise ValueError("submit_input is required")
+        if self.submit_delay_seconds < 0:
+            raise ValueError("submit_delay_seconds cannot be negative")
+        if not 1 <= self.submit_attempts <= 8:
+            raise ValueError("submit_attempts must be between 1 and 8")
+
+
+@dataclass(frozen=True)
+class PromptInjection:
+    prompt: str
+    policy: RuntimeInjectionPolicy
+
+
+class ChannelPromptInjector:
+    """Coordinates an input transport using an explicit runtime policy."""
+
+    def __init__(
+        self,
+        *,
+        sleep: Callable[[float], None],
+        retry_delay_seconds: Callable[[], float],
+        snapshot: Callable[[], str | None],
+        log: Callable[[str, str], None],
+    ) -> None:
+        self._sleep = sleep
+        self._retry_delay_seconds = retry_delay_seconds
+        self._snapshot = snapshot
+        self._log = log
+
+    def inject(self, transport: InputTransport, request: PromptInjection) -> None:
+        policy = request.policy
+        prompt = request.prompt.encode("utf-8", errors="replace")
+        payload = policy.clear_input + prompt
+        if policy.bracketed_paste:
+            payload = policy.clear_input + b"\x1b[200~" + prompt + b"\x1b[201~"
+        transport.write(payload)
+
+        if not transport.wait_until_input_consumed(policy.input_drain_timeout_seconds):
+            self._log("WARN", "channel_input_drain_timeout")
+        if policy.submit_delay_seconds:
+            self._sleep(policy.submit_delay_seconds)
+
+        before = self._snapshot() if policy.confirm_submission and policy.submit_attempts > 1 else None
+        for attempt in range(policy.submit_attempts):
+            transport.write(policy.submit_input)
+            if attempt >= policy.submit_attempts - 1 or not before:
+                break
+            retry_delay = self._retry_delay_seconds()
+            if retry_delay:
+                self._sleep(retry_delay)
+            after = self._snapshot()
+            if after and after != before:
+                self._log("INFO", f"channel_stdin_proxy_submit_confirmed attempt={attempt + 1}")
+                break
+
+
+class CallableInputTransport:
+    """Compatibility adapter for existing descriptors and writer objects."""
+
+    def __init__(self, target: object, write: Callable[[object, bytes], None]) -> None:
+        self._target = target
+        self._write = write
+
+    def write(self, data: bytes) -> None:
+        self._write(self._target, data)
+
+    def wait_until_input_consumed(self, timeout_seconds: float = 2.0) -> bool:
+        wait = getattr(self._target, "wait_until_input_consumed", None)
+        return bool(wait(timeout_seconds)) if callable(wait) else True
+
+
+__all__ = [
+    "CallableInputTransport",
+    "ChannelPromptInjector",
+    "InputTransport",
+    "PromptInjection",
+    "RuntimeInjectionPolicy",
+]

package/ciel_runtime_support/channel_launch_guard_repository.py

@@ -0,0 +1,58 @@
+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 ChannelLaunchGuardRepository:
+    path: Path
+    now: Callable[[], float]
+    log: Callable[[str, str], None]
+
+    def read(self) -> dict[str, Any] | 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_llm_launch_guard_read_failed error={type(exc).__name__}: {exc}",
+            )
+            return None
+        if not isinstance(data, dict):
+            self.log("WARN", "channel_llm_launch_guard_read_failed error=invalid_payload")
+            return None
+        try:
+            expires_at = float(data.get("expires_at") or 0)
+            max_existing_id = int(data.get("max_existing_id") or 0)
+        except (TypeError, ValueError) as exc:
+            self.log(
+                "WARN",
+                f"channel_llm_launch_guard_read_failed error={type(exc).__name__}: {exc}",
+            )
+            return None
+        if expires_at <= self.now() or max_existing_id <= 0:
+            return None
+        return {"max_existing_id": max_existing_id, "expires_at": expires_at}
+
+    def write(self, max_existing_id: int, ttl_seconds: float = 180.0) -> None:
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            now = self.now()
+            payload = {
+                "created_at": now,
+                "expires_at": now + max(1.0, float(ttl_seconds)),
+                "max_existing_id": max(0, int(max_existing_id)),
+            }
+            temporary = self.path.with_suffix(".json.tmp")
+            temporary.write_text(json.dumps(payload, separators=(",", ":")) + "\n", encoding="utf-8")
+            temporary.replace(self.path)
+        except (OSError, TypeError, ValueError, OverflowError) as exc:
+            self.log(
+                "WARN",
+                f"channel_llm_launch_guard_write_failed error={type(exc).__name__}: {exc}",
+            )

package/ciel_runtime_support/channel_launch_policy.py

@@ -0,0 +1,180 @@
+"""Channel launch-mode decisions and Claude channel capability probe."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import subprocess
+from typing import Any, Protocol
+
+
+RuntimeConfig = dict[str, Any]
+
+
+class PassthroughOptionQuery(Protocol):
+    def __call__(self, passthrough: list[str], *names: str) -> bool: ...
+
+
+class ChannelSpecQuery(Protocol):
+    def __call__(
+        self,
+        config: RuntimeConfig,
+        passthrough: list[str],
+        extra_specs: list[str] | None = None,
+    ) -> list[str]: ...
+
+
+class ChannelDeliveryModeQuery(Protocol):
+    def __call__(self, config: RuntimeConfig | None = None) -> str: ...
+
+
+class AuthStatusRunner(Protocol):
+    def __call__(
+        self,
+        command: list[str],
+        *,
+        text: bool,
+        stdout: int,
+        stderr: int,
+        timeout: float,
+    ) -> subprocess.CompletedProcess[str]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelLaunchPorts:
+    has_option: PassthroughOptionQuery
+    channel_specs: ChannelSpecQuery
+    delivery_mode: ChannelDeliveryModeQuery
+    run_auth_status: AuthStatusRunner
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelLaunchPolicy:
+    native_router_names: frozenset[str]
+    ports: ChannelLaunchPorts
+
+    def native_passthrough_requested(self, passthrough: list[str]) -> bool:
+        return self.ports.has_option(
+            passthrough,
+            "--channels",
+            "--dangerously-load-development-channels",
+        )
+
+    def claude_args(
+        self,
+        config: RuntimeConfig,
+        passthrough: list[str],
+        extra_specs: list[str] | None = None,
+        *,
+        native_channel_bridge: bool = False,
+    ) -> list[str]:
+        if not native_channel_bridge:
+            return []
+        if self.native_passthrough_requested(passthrough):
+            return []
+        specs = [
+            spec
+            for spec in self.ports.channel_specs(
+                config,
+                passthrough,
+                extra_specs,
+            )
+            if not self._native_router_spec(spec)
+        ]
+        if not specs:
+            return []
+        return ["--dangerously-load-development-channels", *specs]
+
+    def native_bridge(
+        self,
+        use_router_mode: bool,
+        config: RuntimeConfig,
+        passthrough: list[str],
+    ) -> bool:
+        return bool(
+            not use_router_mode
+            and self.ports.delivery_mode(config) == "native"
+            and not self.native_passthrough_requested(passthrough)
+        )
+
+    def llm_delivery(
+        self,
+        use_router_mode: bool,
+        passthrough: list[str],
+    ) -> bool:
+        return bool(
+            use_router_mode
+            and not self.native_passthrough_requested(passthrough)
+        )
+
+    def stdin_proxy(
+        self,
+        use_router_mode: bool,
+        passthrough: list[str],
+        config: RuntimeConfig | None = None,
+    ) -> bool:
+        if not self.llm_delivery(use_router_mode, passthrough):
+            return False
+        if self.ports.has_option(passthrough, "-p", "--print"):
+            return False
+        claude_config = (
+            config.get("claude_code")
+            if isinstance(config, dict)
+            else {}
+        )
+        if (
+            isinstance(claude_config, dict)
+            and claude_config.get("web_chat_session_bridge") is False
+        ):
+            return False
+        return self.ports.delivery_mode(config) == "llm"
+
+    @staticmethod
+    def process_starts_sse(
+        stdin_proxy: bool,
+        native_bridge: bool,
+        llm_delivery: bool,
+    ) -> bool:
+        return bool((stdin_proxy or native_bridge) and not llm_delivery)
+
+    def specs_include_external_server(self, specs: list[str]) -> bool:
+        for spec in specs:
+            text = str(spec or "").strip()
+            if not text:
+                continue
+            name = text.split(":", 1)[1] if ":" in text else text
+            if name.strip().lower() not in self.native_router_names:
+                return True
+        return False
+
+    def claude_auth_available(self, executable: str) -> tuple[bool, str]:
+        try:
+            process = self.ports.run_auth_status(
+                [executable, "auth", "status"],
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=5,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            return True, f"auth_status_unavailable:{type(exc).__name__}"
+        if process.returncode != 0:
+            return True, f"auth_status_rc_{process.returncode}"
+        try:
+            data = json.loads(process.stdout or "{}")
+        except (json.JSONDecodeError, TypeError):
+            return True, "auth_status_unparseable"
+        if not bool(data.get("loggedIn")):
+            return False, "not_logged_in"
+        return True, str(data.get("authMethod") or "logged_in")
+
+    def _native_router_spec(self, spec: str) -> bool:
+        text = str(spec)
+        return bool(
+            text.startswith("server:")
+            and text.split(":", 1)[1].strip().lower()
+            in self.native_router_names
+        )
+
+
+__all__ = ["ChannelLaunchPolicy", "ChannelLaunchPorts"]

package/ciel_runtime_support/channel_llm_context.py

@@ -0,0 +1,156 @@
+"""Inject pending channel messages into an LLM request context."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+INTERNAL_METADATA_PREFIX = "ciel_runtime_"
+
+
+def strip_internal_metadata(body: dict[str, Any]) -> dict[str, Any]:
+    """Return the original body unless private metadata requires projection."""
+
+    metadata = body.get("metadata")
+    if not isinstance(metadata, dict) or not metadata:
+        return body
+    public_metadata = {
+        key: value
+        for key, value in metadata.items()
+        if not str(key).startswith(INTERNAL_METADATA_PREFIX)
+    }
+    if len(public_metadata) == len(metadata):
+        return body
+    projected = dict(body)
+    if public_metadata:
+        projected["metadata"] = public_metadata
+    else:
+        projected.pop("metadata", None)
+    return projected
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelLlmContextPolicy:
+    wake_request: Callable[[dict[str, Any]], bool]
+    plan_mode_active: Callable[[dict[str, Any]], bool]
+    delivery_mode: Callable[[], str]
+    ids_in_request: Callable[[dict[str, Any]], set[int]]
+    scan_limit: Callable[[], int]
+    skip_reason: Callable[[dict[str, Any]], str]
+    stdin_skip_reason: Callable[[int], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelLlmContextRepository:
+    lock: Callable[[], Any]
+    read_cursor: Callable[[], int]
+    commit_cursor: Callable[[int], None]
+    read_messages: Callable[[int, int], list[dict[str, Any]]]
+    superseded_ids: Callable[[list[dict[str, Any]]], set[int]]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelLlmContextProjection:
+    remove_wake_prompt: Callable[[dict[str, Any]], dict[str, Any]]
+    format_prompt: Callable[[list[dict[str, Any]]], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelLlmContextServices:
+    policy: ChannelLlmContextPolicy
+    repository: ChannelLlmContextRepository
+    projection: ChannelLlmContextProjection
+    log: Callable[[str, str], Any]
+
+
+def inject_pending_channel_context(
+    body: dict[str, Any],
+    services: ChannelLlmContextServices,
+) -> dict[str, Any]:
+    policy = services.policy
+    repository = services.repository
+    wake_request = policy.wake_request(body)
+    if policy.plan_mode_active(body):
+        if not wake_request:
+            services.log("INFO", "channel_llm_inject_skipped reason=plan_mode_active")
+            return body
+        services.log("INFO", "channel_llm_inject_plan_mode_override reason=channel_wake")
+    if policy.delivery_mode() != "llm":
+        return body
+
+    ids_already_in_request = policy.ids_in_request(body)
+    with repository.lock():
+        last_id = repository.read_cursor()
+        pending: list[dict[str, Any]] = []
+        max_seen = last_id
+        candidates = repository.read_messages(last_id, policy.scan_limit())
+        superseded_ids = repository.superseded_ids(candidates)
+        for message in candidates:
+            try:
+                message_id = int(message.get("id") or 0)
+            except (TypeError, ValueError):
+                continue
+            reason = _candidate_skip_reason(
+                message,
+                message_id,
+                ids_already_in_request,
+                superseded_ids,
+                policy,
+            )
+            if reason:
+                if reason not in {"stdin_wake_delivered", "stdin_wake_claimed"}:
+                    max_seen = max(max_seen, message_id)
+                services.log(
+                    "INFO",
+                    f"channel_llm_inject_skipped message_id={message.get('id')} "
+                    f"channel={message.get('channel')} reason={reason}",
+                )
+                continue
+            pending.append(message)
+            max_seen = message_id
+            break
+        if not pending:
+            if max_seen != last_id:
+                repository.commit_cursor(max_seen)
+            return services.projection.remove_wake_prompt(body) if wake_request else body
+
+    base_body = services.projection.remove_wake_prompt(body) if wake_request else body
+    messages = [message for message in base_body.get("messages", []) if isinstance(message, dict)]
+    messages.append(
+        {
+            "role": "user",
+            "content": [{"type": "text", "text": services.projection.format_prompt(pending)}],
+        }
+    )
+    out = dict(base_body)
+    out["messages"] = messages
+    ids = ",".join(str(message.get("id") or "") for message in pending)
+    channels = ",".join(sorted({str(message.get("channel") or "default") for message in pending}))
+    metadata = dict(out.get("metadata") if isinstance(out.get("metadata"), dict) else {})
+    metadata.update(
+        {
+            "ciel_runtime_channel_injected": True,
+            "ciel_runtime_channel_message_ids": ids,
+            "ciel_runtime_channel_cursor_last_id": str(max_seen),
+        }
+    )
+    out["metadata"] = metadata
+    services.log("INFO", f"channel_llm_injected count={len(pending)} message_ids={ids} channels={channels}")
+    return out
+
+
+def _candidate_skip_reason(
+    message: dict[str, Any],
+    message_id: int,
+    ids_already_in_request: set[int],
+    superseded_ids: set[int],
+    policy: ChannelLlmContextPolicy,
+) -> str:
+    if message_id in ids_already_in_request:
+        return "already_in_request"
+    if message_id in superseded_ids:
+        return "superseded_channel_notice"
+    reason = policy.skip_reason(message)
+    return reason or policy.stdin_skip_reason(message_id)

package/ciel_runtime_support/channel_mcp_discovery.py

@@ -0,0 +1,186 @@
+"""Discover and start HTTP MCP channel transports from configuration files."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelMcpDiscoveryPorts:
+    environment: Mapping[str, str]
+    config_paths: Callable[..., list[Path]]
+    path_key: Callable[[Path], str]
+    read_config: Callable[[Path, Path], list[dict[str, Any]]]
+    dedupe: Callable[[Iterable[str]], list[str]]
+    native_router_names: frozenset[str]
+    public_name: Callable[[str], str]
+    start_connection: Callable[[dict[str, Any]], dict[str, Any]]
+    log: Callable[[str, str], None]
+
+
+class ChannelMcpDiscoveryService:
+    def __init__(self, ports: ChannelMcpDiscoveryPorts) -> None:
+        self.ports = ports
+
+    def runtime_headers(self, server: dict[str, Any]) -> dict[str, str]:
+        headers = server.get("headers")
+        raw_headers = headers if isinstance(headers, dict) else {}
+        projected = {
+            str(key): str(value)
+            for key, value in raw_headers.items()
+            if str(key).strip() and value is not None
+        }
+        env_headers = server.get("env_http_headers")
+        if isinstance(env_headers, dict):
+            for raw_header, raw_environment_name in env_headers.items():
+                header = str(raw_header or "").strip()
+                environment_name = str(raw_environment_name or "").strip()
+                value = self.ports.environment.get(environment_name)
+                if header and environment_name and value:
+                    projected[header] = value
+        token = str(server.get("bearer_token") or server.get("token") or "").strip()
+        token_environment = str(
+            server.get("bearer_token_env_var") or server.get("token_env_var") or ""
+        ).strip()
+        if not token and token_environment:
+            token = str(self.ports.environment.get(token_environment) or "").strip()
+        if token and not any(key.lower() == "authorization" for key in projected):
+            projected["Authorization"] = f"Bearer {token}"
+        return projected
+
+    def servers_from_mapping(self, mapping: Any) -> list[dict[str, Any]]:
+        if not isinstance(mapping, dict):
+            return []
+        found: list[dict[str, Any]] = []
+        for key in ("mcpServers", "servers"):
+            servers = mapping.get(key)
+            if not isinstance(servers, dict):
+                continue
+            for raw_name, raw_server in servers.items():
+                projected = self._project_server(raw_name, raw_server)
+                if projected is not None:
+                    found.append(projected)
+        return found
+
+    def _project_server(
+        self, raw_name: Any, raw_server: Any
+    ) -> dict[str, Any] | None:
+        name = str(raw_name or "").strip()
+        if not name or not isinstance(raw_server, dict):
+            return None
+        url = str(raw_server.get("url") or raw_server.get("endpoint") or "").strip()
+        if not url.startswith(("http://", "https://")):
+            return None
+        server_type = str(raw_server.get("type") or "").strip().lower()
+        if server_type and server_type not in ("sse", "http", "streamable-http"):
+            return None
+        transport = (
+            "streamable-http" if server_type in ("http", "streamable-http") else "sse"
+        )
+        requires_session = raw_server.get(
+            "streamable_requires_session",
+            raw_server.get(
+                "require_session", raw_server.get("mcp_session_required", True)
+            ),
+        )
+        return {
+            "name": f"mcp-{name}",
+            "url": url,
+            "type": server_type or transport,
+            "transport": transport,
+            "headers": self.runtime_headers(raw_server),
+            "channel": name,
+            "sender_id": name,
+            "recipient": "all",
+            "mcp": True,
+            "streamable_requires_session": requires_session,
+        }
+
+    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]:
+        cwd = cwd or Path.cwd()
+        names: list[str] = []
+        for path in self._paths(
+            passthrough, cwd, home, extra_config_paths, include_default=True
+        ):
+            for server in self.ports.read_config(path, cwd):
+                name = str(server.get("channel") or "").strip()
+                if name and name.lower() not in self.ports.native_router_names:
+                    names.append(name)
+        return self.ports.dedupe(names)
+
+    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]]:
+        cwd = cwd or Path.cwd()
+        allowed = (
+            {
+                self.ports.public_name(str(name or "").strip())
+                for name in allowed_server_names
+                if str(name or "").strip()
+            }
+            if allowed_server_names is not None
+            else None
+        )
+        started: list[dict[str, Any]] = []
+        for path in self._paths(
+            passthrough,
+            cwd,
+            home,
+            extra_config_paths,
+            include_default=include_default_paths,
+        ):
+            for server in self.ports.read_config(path, cwd):
+                public_name = self.ports.public_name(str(server.get("name") or ""))
+                if allowed is not None and public_name not in allowed:
+                    continue
+                try:
+                    status = self.ports.start_connection(server)
+                    started.append(status)
+                    self.ports.log(
+                        "INFO",
+                        f"channel_sse_auto_started name={status.get('name')} "
+                        f"url={status.get('url')}",
+                    )
+                except Exception as exc:
+                    self.ports.log(
+                        "WARN",
+                        f"channel_sse_auto_start_failed path={path} "
+                        f"error={type(exc).__name__}: {exc}",
+                    )
+        return started
+
+    def _paths(
+        self,
+        passthrough: list[str] | None,
+        cwd: Path,
+        home: Path | None,
+        extra_config_paths: list[Path | str] | None,
+        *,
+        include_default: bool,
+    ) -> list[Path]:
+        paths = [Path(path).expanduser() for path in extra_config_paths or []]
+        if include_default:
+            paths.extend(self.ports.config_paths(passthrough, cwd, home))
+        unique: list[Path] = []
+        seen: set[str] = set()
+        for path in paths:
+            key = self.ports.path_key(path)
+            if key not in seen and path.is_file():
+                seen.add(key)
+                unique.append(path)
+        return unique