@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/command_asset_installer.py

@@ -0,0 +1,103 @@
+"""Ownership-aware installer for Claude commands and Codex prompts."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+
+@dataclass(frozen=True, slots=True)
+class CommandAsset:
+    content: str
+    ownership_markers: tuple[str, ...]
+
+
+def is_owned_command_file(path: Path, markers: tuple[str, ...]) -> bool:
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        return False
+    return any(marker in text for marker in markers)
+
+
+@dataclass(frozen=True, slots=True)
+class CommandAssetInstaller:
+    directory: Path
+    warn: Callable[[str], None]
+
+    def install_one(self, name: str, asset: CommandAsset) -> None:
+        try:
+            self.directory.mkdir(parents=True, exist_ok=True)
+            path = self.directory / name
+            if path.exists():
+                existing = path.read_text(encoding="utf-8", errors="replace")
+                if existing == asset.content:
+                    return
+                if not is_owned_command_file(path, asset.ownership_markers):
+                    return
+            path.write_text(asset.content, encoding="utf-8")
+            try:
+                os.chmod(path, 0o600)
+            except Exception:
+                pass
+        except Exception as error:
+            self.warn(f"could not install {name} ({type(error).__name__}: {error}).")
+
+    def remove_one(self, name: str, markers: tuple[str, ...]) -> None:
+        try:
+            path = self.directory / name
+            if path.exists() and is_owned_command_file(path, markers):
+                path.unlink()
+        except Exception as error:
+            self.warn(f"could not remove {name} ({type(error).__name__}: {error}).")
+
+    def install_all(
+        self,
+        assets: dict[str, CommandAsset],
+        stale_glob: str | None = None,
+        stale_markers: tuple[str, ...] = (),
+    ) -> None:
+        try:
+            self.directory.mkdir(parents=True, exist_ok=True)
+            if stale_glob:
+                for path in self.directory.glob(stale_glob):
+                    if path.name not in assets and is_owned_command_file(path, stale_markers):
+                        try:
+                            path.unlink()
+                        except Exception:
+                            pass
+            stale_channel = self.directory / "channel.md"
+            if stale_channel.exists() and is_owned_command_file(
+                stale_channel,
+                ("CIEL_RUNTIME_CHANNEL_BRIDGE", "ciel-runtime channel bridge"),
+            ):
+                try:
+                    stale_channel.unlink()
+                except Exception:
+                    pass
+            for name, asset in assets.items():
+                self.install_one(name, asset)
+        except Exception as error:
+            self.warn(f"could not install command assets ({type(error).__name__}: {error}).")
+
+    def remove_all(
+        self,
+        assets: dict[str, CommandAsset],
+        stale_glob: str | None = None,
+        stale_markers: tuple[str, ...] = (),
+    ) -> None:
+        try:
+            if not self.directory.exists():
+                return
+            for name, asset in assets.items():
+                path = self.directory / name
+                if path.exists() and is_owned_command_file(path, asset.ownership_markers):
+                    path.unlink()
+            if stale_glob:
+                for path in self.directory.glob(stale_glob):
+                    if path.name not in assets and is_owned_command_file(path, stale_markers):
+                        path.unlink()
+        except Exception as error:
+            self.warn(f"could not remove command assets ({type(error).__name__}: {error}).")

package/ciel_runtime_support/compatibility_probe.py

@@ -0,0 +1,295 @@
+"""Provider-aware API-key compatibility probe request builder."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Protocol
+import urllib.error
+
+from .architecture import ProviderRequestPolicy
+
+
+ProviderConfig = dict[str, Any]
+RequestBody = dict[str, Any]
+
+
+class CompatibilityApiKeyProbeError(Exception):
+    def __init__(
+        self,
+        message: str,
+        code: int | None = None,
+        diagnosis: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.diagnosis = diagnosis
+
+
+class OllamaProbeRequest(Protocol):
+    def __call__(
+        self,
+        model: str,
+        body: RequestBody,
+        config: ProviderConfig,
+        *,
+        stream: bool,
+        provider: str,
+    ) -> RequestBody: ...
+
+
+class OpenAiProbeRequest(Protocol):
+    def __call__(
+        self,
+        provider: str,
+        model: str,
+        body: RequestBody,
+        config: ProviderConfig,
+        *,
+        stream: bool,
+    ) -> RequestBody: ...
+
+
+class ProbePost(Protocol):
+    def __call__(
+        self,
+        url: str,
+        body: RequestBody,
+        *,
+        headers: dict[str, str],
+        timeout: float,
+        provider: str,
+        pcfg: ProviderConfig,
+    ) -> Any: ...
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityProbeProjectionPorts:
+    normalize_thinking: Callable[
+        [str, ProviderConfig, RequestBody],
+        RequestBody,
+    ]
+    normalize_tool_choice: Callable[
+        [str, ProviderConfig, RequestBody],
+        RequestBody,
+    ]
+    resolve_model: Callable[[str, ProviderConfig, str], str]
+    headers: Callable[[str, ProviderConfig], dict[str, str]]
+    request_policy: Callable[
+        [str, ProviderConfig],
+        ProviderRequestPolicy,
+    ]
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityProbeRoutingPorts:
+    ollama_request: OllamaProbeRequest
+    openai_request: OpenAiProbeRequest
+    endpoint: Callable[[str, ProviderConfig, str], str]
+    opencode_endpoint_kind: Callable[[str, str, ProviderConfig], str]
+    openai_router_enabled: Callable[[str, ProviderConfig], bool]
+    request_base: Callable[[str, ProviderConfig], str]
+    join_url: Callable[[str, str], str]
+    ncp_model_id: Callable[[str], str]
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityProbeAnthropicPorts:
+    cap_body: Callable[[str, ProviderConfig, RequestBody], RequestBody]
+    apply_options: Callable[[str, ProviderConfig, RequestBody], RequestBody]
+    resolve_tool_models: Callable[
+        [str, ProviderConfig, RequestBody],
+        RequestBody,
+    ]
+    native_compat_enabled: Callable[[str, ProviderConfig], bool]
+    native_base_url: Callable[[str, ProviderConfig], str]
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityApiKeyProbeBuilder:
+    projection: CompatibilityProbeProjectionPorts
+    routing: CompatibilityProbeRoutingPorts
+    anthropic: CompatibilityProbeAnthropicPorts
+
+    def build(
+        self,
+        provider: str,
+        config: ProviderConfig,
+        model: str,
+        request_body: RequestBody,
+    ) -> tuple[str, RequestBody, dict[str, str]]:
+        body = self.projection.normalize_thinking(
+            provider,
+            config,
+            request_body,
+        )
+        body = self.projection.normalize_tool_choice(provider, config, body)
+        upstream_model = self.projection.resolve_model(provider, config, model)
+        headers = self.projection.headers(provider, config)
+        policy = self.projection.request_policy(provider, config)
+
+        if policy.probe_strategy == "ollama":
+            probe_body = self.routing.ollama_request(
+                upstream_model,
+                body,
+                config,
+                stream=False,
+                provider=provider,
+            )
+            return (
+                self.routing.endpoint(provider, config, "ollama_chat"),
+                probe_body,
+                headers,
+            )
+
+        if policy.probe_strategy == "opencode":
+            endpoint_kind = self.routing.opencode_endpoint_kind(
+                provider,
+                upstream_model,
+                config,
+            )
+            if endpoint_kind == "openai-chat":
+                probe_body = self.routing.openai_request(
+                    provider,
+                    upstream_model,
+                    body,
+                    config,
+                    stream=False,
+                )
+                url = self.routing.join_url(
+                    self.routing.request_base(provider, config),
+                    "/v1/chat/completions",
+                )
+                return url, probe_body, headers
+            if endpoint_kind != "anthropic-messages":
+                raise CompatibilityApiKeyProbeError(
+                    f"model {upstream_model!r} uses unsupported endpoint family "
+                    f"{endpoint_kind!r} for API-key probing"
+                )
+
+        if self.routing.openai_router_enabled(provider, config):
+            if policy.model_alias_strategy == "ncp":
+                upstream_model = self.routing.ncp_model_id(upstream_model)
+            probe_body = self.routing.openai_request(
+                provider,
+                upstream_model,
+                body,
+                config,
+                stream=False,
+            )
+            return (
+                self.routing.endpoint(provider, config, "openai_chat"),
+                probe_body,
+                headers,
+            )
+
+        body = self.anthropic.cap_body(provider, config, body)
+        body = self.anthropic.apply_options(provider, config, body)
+        body = dict(body)
+        body["model"] = upstream_model
+        body = self.anthropic.resolve_tool_models(provider, config, body)
+        if self.anthropic.native_compat_enabled(provider, config):
+            base = self.anthropic.native_base_url(provider, config)
+        else:
+            base = self.routing.request_base(provider, config)
+        return self.routing.join_url(base, "/v1/messages"), body, headers
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityApiKeyProbeRunnerPorts:
+    api_keys: Callable[[str, ProviderConfig], list[str]]
+    mask_secret: Callable[[str], str]
+    build_request: Callable[
+        [str, ProviderConfig, str, RequestBody],
+        tuple[str, RequestBody, dict[str, str]],
+    ]
+    post: ProbePost
+    http_error_message: Callable[[urllib.error.HTTPError], str]
+    failure_diagnosis: Callable[[str, int | None, str], str | None]
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityApiKeyProbeRunner:
+    ports: CompatibilityApiKeyProbeRunnerPorts
+
+    @staticmethod
+    def single_key_config(
+        config: ProviderConfig,
+        key: str,
+    ) -> ProviderConfig:
+        keyed = dict(config)
+        keyed["api_key"] = key
+        keyed["api_keys"] = []
+        return keyed
+
+    def run(
+        self,
+        provider: str,
+        config: ProviderConfig,
+        model: str,
+        request_body: RequestBody,
+        timeout: float,
+    ) -> list[str]:
+        keys = self.ports.api_keys(provider, config)
+        if len(keys) <= 1:
+            return []
+        lines = [f"API key checks: running {len(keys)} configured keys"]
+        for index, key in enumerate(keys, start=1):
+            label = (
+                f"API key {index}/{len(keys)} "
+                f"({self.ports.mask_secret(key)})"
+            )
+            keyed_config = self.single_key_config(config, key)
+            try:
+                url, body, headers = self.ports.build_request(
+                    provider,
+                    keyed_config,
+                    model,
+                    request_body,
+                )
+                self.ports.post(
+                    url,
+                    body,
+                    headers=headers,
+                    timeout=timeout,
+                    provider=provider,
+                    pcfg=keyed_config,
+                )
+            except CompatibilityApiKeyProbeError:
+                raise
+            except urllib.error.HTTPError as exc:
+                message = self.ports.http_error_message(exc)
+                diagnosis = (
+                    self.ports.failure_diagnosis(
+                        provider,
+                        exc.code,
+                        message,
+                    )
+                    or ""
+                )
+                raise CompatibilityApiKeyProbeError(
+                    f"{label}: {message}",
+                    exc.code,
+                    diagnosis,
+                ) from exc
+            except TimeoutError as exc:
+                raise CompatibilityApiKeyProbeError(
+                    f"{label}: timed out before the {timeout:g}s "
+                    "API-key probe timeout"
+                ) from exc
+            except Exception as exc:
+                raise CompatibilityApiKeyProbeError(
+                    f"{label}: {type(exc).__name__}: {exc}"
+                ) from exc
+            lines.append(f"{label}: OK")
+        return lines
+
+
+__all__ = [
+    "CompatibilityApiKeyProbeBuilder",
+    "CompatibilityApiKeyProbeError",
+    "CompatibilityApiKeyProbeRunner",
+    "CompatibilityApiKeyProbeRunnerPorts",
+    "CompatibilityProbeAnthropicPorts",
+    "CompatibilityProbeProjectionPorts",
+    "CompatibilityProbeRoutingPorts",
+]

package/ciel_runtime_support/compatibility_protocol.py

@@ -0,0 +1,251 @@
+"""Protocol codec for provider compatibility probes."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+import urllib.error
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityProtocolPorts:
+    max_tokens_for_model: Callable[[str], int]
+    first_header: Callable[[Any, list[str]], str | None]
+    parse_retry_after: Callable[[str], float | None]
+    format_duration: Callable[[float], str]
+
+
+class CompatibilityProtocolCodec:
+    def __init__(self, tool_name: str, ports: CompatibilityProtocolPorts) -> None:
+        self.tool_name = tool_name
+        self.ports = ports
+
+    def tool_schema(self) -> dict[str, Any]:
+        return {
+            "name": self.tool_name,
+            "description": "A minimal compatibility test tool. It echoes one required text argument.",
+            "input_schema": {
+                "type": "object",
+                "properties": {"text": {"type": "string"}},
+                "required": ["text"],
+                "additionalProperties": False,
+            },
+        }
+
+    def text_request(self, model: str) -> dict[str, Any]:
+        return {
+            "model": model,
+            "max_tokens": self.ports.max_tokens_for_model(model),
+            "stream": False,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": "Compatibility text test. Reply with exactly OK and do not call tools.",
+                }
+            ],
+        }
+
+    def tool_request(self, model: str) -> dict[str, Any]:
+        return {
+            "model": model,
+            "max_tokens": 128,
+            "stream": False,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": "Compatibility tool test. Use the compat_echo tool exactly once with text set to ping.",
+                }
+            ],
+            "tools": [self.tool_schema()],
+            "tool_choice": {"type": "tool", "name": self.tool_name},
+        }
+
+    def tool_result_request(
+        self,
+        model: str,
+        tool_use: dict[str, Any],
+    ) -> dict[str, Any]:
+        tool_id = str(tool_use.get("id") or "toolu_compat_echo_1")
+        tool_input = (
+            tool_use.get("input")
+            if isinstance(tool_use.get("input"), dict)
+            else {"text": "ping"}
+        )
+        return {
+            "model": model,
+            "max_tokens": 64,
+            "stream": False,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": "Compatibility tool test. Use the compat_echo tool exactly once with text set to ping.",
+                },
+                {
+                    "role": "assistant",
+                    "content": [
+                        {
+                            "type": "tool_use",
+                            "id": tool_id,
+                            "name": self.tool_name,
+                            "input": tool_input,
+                        }
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": tool_id,
+                            "content": "pong",
+                        },
+                        {
+                            "type": "text",
+                            "text": "Now reply with FINAL_OK and do not call tools.",
+                        },
+                    ],
+                },
+            ],
+            "tools": [self.tool_schema()],
+        }
+
+    @staticmethod
+    def content_blocks(data: Any) -> list[dict[str, Any]]:
+        if not isinstance(data, dict):
+            return []
+        content = data.get("content")
+        if not isinstance(content, list):
+            return []
+        return [block for block in content if isinstance(block, dict)]
+
+    def content_types(self, data: Any) -> list[str]:
+        return [str(block.get("type", "?")) for block in self.content_blocks(data)]
+
+    def text_preview(self, data: Any) -> str:
+        parts = [
+            block["text"].strip()
+            for block in self.content_blocks(data)
+            if block.get("type") == "text" and isinstance(block.get("text"), str)
+        ]
+        return " ".join(parts).strip()[:300]
+
+    def find_tool_use(self, data: Any) -> tuple[dict[str, Any] | None, str]:
+        for block in self.content_blocks(data):
+            if block.get("type") != "tool_use":
+                continue
+            if block.get("name") != self.tool_name:
+                return None, f"unexpected tool name {block.get('name')!r}"
+            tool_input = block.get("input")
+            if not isinstance(tool_input, dict):
+                return None, "tool input was not a JSON object"
+            if tool_input.get("text") != "ping":
+                return None, (
+                    f"tool input text was {tool_input.get('text')!r}, expected 'ping'"
+                )
+            if not block.get("id"):
+                return None, "tool_use block did not include an id"
+            return block, ""
+        types = ", ".join(self.content_types(data)) or "none"
+        preview = self.text_preview(data)
+        suffix = f"; text={preview!r}" if preview else ""
+        return None, (
+            f"no {self.tool_name} tool_use block returned; "
+            f"content blocks: {types}{suffix}"
+        )
+
+    def summarize_response(self, data: Any, label: str) -> list[str]:
+        lines = [f"{label}: OK"]
+        if not isinstance(data, dict):
+            return lines
+        stop = data.get("stop_reason")
+        if stop:
+            lines.append(f"Stop reason: {stop}")
+        types = self.content_types(data)
+        if types:
+            lines.append("Content blocks: " + ", ".join(types[:6]))
+        usage = data.get("usage")
+        if isinstance(usage, dict):
+            tokens = []
+            if "input_tokens" in usage:
+                tokens.append(f"in={usage['input_tokens']}")
+            if "output_tokens" in usage:
+                tokens.append(f"out={usage['output_tokens']}")
+            if tokens:
+                lines.append("Tokens: " + ", ".join(tokens))
+        return lines
+
+    def http_error_message(self, exc: urllib.error.HTTPError) -> str:
+        raw = exc.read().decode("utf-8", errors="ignore")
+        message = raw.strip()
+        error_type = ""
+        try:
+            error = json.loads(raw)
+            if isinstance(error, dict):
+                if isinstance(error.get("error"), dict):
+                    error_object = error["error"]
+                    error_type = str(error_object.get("type") or "").strip()
+                    message = str(
+                        error_object.get("message")
+                        or json.dumps(error_object, ensure_ascii=False)
+                    )
+                elif error.get("message"):
+                    message = str(error["message"])
+                    error_type = str(error.get("type") or "").strip()
+        except Exception:
+            pass
+        if error_type and error_type not in message:
+            message = f"{error_type}: {message}"
+        retry_after = self.ports.first_header(
+            exc.headers,
+            ["Retry-After", "retry-after"],
+        )
+        if not retry_after:
+            return message
+        retry_text = retry_after.strip()
+        retry_seconds = self.ports.parse_retry_after(retry_text)
+        if retry_seconds is None:
+            return f"{message} Retry-After: {retry_text}"
+        display = self.ports.format_duration(retry_seconds)
+        if not retry_text:
+            return f"{message} Retry-After: {display}"
+        raw_suffix = f"{retry_text}s" if re.fullmatch(r"\d+(?:\.\d+)?", retry_text) else retry_text
+        return f"{message} Retry-After: {display} ({raw_suffix})"
+
+
+@dataclass(frozen=True, slots=True)
+class CompatibilityProtocolApi:
+    """Explicit compatibility facade backed by a late-bound protocol codec."""
+
+    codec_factory: Callable[[], CompatibilityProtocolCodec]
+
+    def tool_schema(self) -> dict[str, Any]:
+        return self.codec_factory().tool_schema()
+
+    def text_request(self, model: str) -> dict[str, Any]:
+        return self.codec_factory().text_request(model)
+
+    def tool_request(self, model: str) -> dict[str, Any]:
+        return self.codec_factory().tool_request(model)
+
+    def tool_result_request(
+        self, model: str, tool_use: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self.codec_factory().tool_result_request(model, tool_use)
+
+    def content_types(self, data: Any) -> list[str]:
+        return self.codec_factory().content_types(data)
+
+    def text_preview(self, data: Any) -> str:
+        return self.codec_factory().text_preview(data)
+
+    def find_tool_use(self, data: Any) -> tuple[dict[str, Any] | None, str]:
+        return self.codec_factory().find_tool_use(data)
+
+    def summarize_response(self, data: Any, label: str) -> list[str]:
+        return self.codec_factory().summarize_response(data, label)
+
+    def http_error_message(self, exc: urllib.error.HTTPError) -> str:
+        return self.codec_factory().http_error_message(exc)