@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/router_server_runtime.py

@@ -0,0 +1,103 @@
+"""Router HTTP server startup and shutdown application service."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+
+@dataclass(frozen=True, slots=True)
+class RouterServerConfig:
+    config_dir: Path
+    pid_path: Path
+    port: int
+    client_base: str
+    log_level_path: Path
+    log_level_names: dict[Any, Any]
+    handler: Any
+
+
+@dataclass(frozen=True, slots=True)
+class RouterServerStatePorts:
+    load_config: Callable[[], dict[str, Any]]
+    reset_api_key_cooldowns: Callable[[], None]
+    bind_host: Callable[[dict[str, Any]], str]
+    current_log_level: Callable[[], Any]
+    current_pid: Callable[[], int]
+    env_value: Callable[[str], str | None]
+    external_access_enabled: Callable[[dict[str, Any]], bool]
+    ensure_external_token: Callable[[], str]
+
+
+@dataclass(frozen=True, slots=True)
+class RouterServerEffects:
+    chmod: Callable[[Path, int], None]
+    stderr: Any
+    server_factory: Callable[..., Any]
+    start_watchdog: Callable[[Any], None]
+    start_channels: Callable[[dict[str, Any]], Any]
+    stop_channels: Callable[[None], Any]
+    thread_factory: Callable[..., Any]
+    configure_web_endpoints: Callable[[str], list[str]]
+
+
+@dataclass(frozen=True, slots=True)
+class RouterServerRuntime:
+    config: RouterServerConfig
+    state: RouterServerStatePorts
+    effects: RouterServerEffects
+
+    def run(self) -> None:
+        self.config.config_dir.mkdir(parents=True, exist_ok=True)
+        runtime_config = self.state.load_config()
+        self.state.reset_api_key_cooldowns()
+        bind_host = self.state.bind_host(runtime_config)
+        if self.state.external_access_enabled(runtime_config):
+            self.state.ensure_external_token()
+        self.config.pid_path.write_text(str(self.state.current_pid()))
+        self.effects.chmod(self.config.pid_path, 0o600)
+        level = self.state.current_log_level()
+        source = self._log_level_source()
+        self.effects.stderr.write(
+            f"ciel-runtime router starting on {bind_host}:{self.config.port} "
+            f"(client base {self.config.client_base}, log level "
+            f"{self.config.log_level_names.get(level, level)}, source={source})\n"
+        )
+        self.effects.stderr.flush()
+        server = self.effects.server_factory(
+            (bind_host, self.config.port), self.config.handler
+        )
+        for line in self.effects.configure_web_endpoints(bind_host):
+            self.effects.stderr.write(f"{line}\n")
+        self.effects.stderr.flush()
+        self.effects.start_watchdog(server)
+        channel_thread = self.effects.thread_factory(
+            target=lambda: self.effects.start_channels(runtime_config),
+            daemon=True,
+            name="ca-router-channel-sse-start",
+        )
+        channel_thread.start()
+        try:
+            server.serve_forever()
+        finally:
+            self.effects.stop_channels(None)
+            try:
+                self.config.pid_path.unlink()
+            except FileNotFoundError:
+                pass
+
+    def _log_level_source(self) -> str:
+        if self.config.log_level_path.exists():
+            return "file"
+        if self.state.env_value("CIEL_RUNTIME_LOG_LEVEL"):
+            return "env"
+        return "default"
+
+
+__all__ = [
+    "RouterServerConfig",
+    "RouterServerEffects",
+    "RouterServerRuntime",
+    "RouterServerStatePorts",
+]

package/ciel_runtime_support/router_shortcuts.py

@@ -0,0 +1,201 @@
+"""Local router slash-command short-circuit controllers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Protocol
+
+
+class ShortcutHandler(Protocol):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class ShortcutResponsePorts:
+    load_config: Callable[[], dict[str, Any]]
+    current_alias: Callable[[dict[str, Any]], str]
+    current_provider: Callable[[dict[str, Any]], tuple[str, dict[str, Any]]]
+    write_anthropic: Callable[..., Any]
+    publish_event: Callable[..., Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ShortcutPredicates:
+    router_debug: Callable[[dict[str, Any]], bool]
+    version: Callable[[dict[str, Any]], bool]
+    channel_clear: Callable[[dict[str, Any]], bool]
+    live_llm_options: Callable[[dict[str, Any]], bool]
+    live_api_keys: Callable[[dict[str, Any]], bool]
+
+
+@dataclass(frozen=True, slots=True)
+class RouterDebugShortcutPorts:
+    value: Callable[[dict[str, Any]], str]
+    external_enabled: Callable[[dict[str, Any]], bool]
+    bind_host: Callable[[dict[str, Any]], str]
+    set_external: Callable[[Any], list[str]]
+    schedule_restart: Callable[[], Any]
+    version: str
+    source_fingerprint: str
+    config_dir: Path
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelShortcutPorts:
+    value: Callable[[dict[str, Any]], str]
+    clear: Callable[[], dict[str, Any]]
+    status: Callable[[], dict[str, Any]]
+
+
+@dataclass(frozen=True, slots=True)
+class LiveConfigShortcutPorts:
+    llm_value: Callable[[dict[str, Any]], str]
+    handle_llm: Callable[[str], tuple[list[str], bool]]
+    api_key_value: Callable[[dict[str, Any]], str]
+    handle_api_keys: Callable[[str], tuple[list[str], bool]]
+    api_key_count: Callable[[str, dict[str, Any]], int]
+
+
+@dataclass(frozen=True, slots=True)
+class RouterShortcutController:
+    response: ShortcutResponsePorts
+    predicates: ShortcutPredicates
+    debug: RouterDebugShortcutPorts
+    channel: ChannelShortcutPorts
+    live: LiveConfigShortcutPorts
+
+    def _model_and_stream(self, body: dict[str, Any]) -> tuple[str, bool]:
+        config = self.response.load_config()
+        return (
+            str(body.get("model") or self.response.current_alias(config)),
+            bool(body.get("stream", True)),
+        )
+
+    def handle_router_debug(self, handler: ShortcutHandler, body: dict[str, Any]) -> bool:
+        if not self.predicates.router_debug(body):
+            return False
+        config = self.response.load_config()
+        current = self.debug.external_enabled(config)
+        value = self.debug.value(body).strip().lower()
+        should_restart = False
+        if value in {"", "status", "state", "show", "?"}:
+            lines = [
+                f"Router debug external access: {'on' if current else 'off'}.",
+                f"Current router bind host: {self.debug.bind_host(config)}.",
+            ]
+        elif value in {"toggle", "tog", "switch"}:
+            lines = self.debug.set_external(not current)
+            should_restart = True
+        elif value in {"on", "true", "1", "enable", "enabled"}:
+            lines = self.debug.set_external(True)
+            should_restart = True
+        elif value in {"off", "false", "0", "disable", "disabled"}:
+            lines = self.debug.set_external(False)
+            should_restart = True
+        else:
+            lines = [
+                "Usage: `/router-debug`, `/router-debug on`, `/router-debug off`, or `/router-debug status`."
+            ]
+        if should_restart:
+            lines.append("Router restart scheduled so the bind address changes immediately.")
+        model, stream = self._model_and_stream(body)
+        self.response.write_anthropic(handler, model, "\n".join(lines), stream)
+        if should_restart:
+            self.debug.schedule_restart()
+        return True
+
+    def handle_version(self, handler: ShortcutHandler, body: dict[str, Any]) -> bool:
+        if not self.predicates.version(body):
+            return False
+        lines = [
+            f"ciel-runtime {self.debug.version}",
+            f"source: {self.debug.source_fingerprint[:12]}",
+            f"config dir: {self.debug.config_dir}",
+        ]
+        model, stream = self._model_and_stream(body)
+        self.response.write_anthropic(handler, model, "\n".join(lines), stream)
+        return True
+
+    @staticmethod
+    def channel_status_lines(stats: dict[str, Any], cleared: bool) -> list[str]:
+        if cleared:
+            return [
+                "Ciel Runtime channel backlog discarded.",
+                f"- chat tail: {stats.get('chat_tail')}",
+                f"- LLM cursor advanced by: {stats.get('discarded_llm')}",
+                f"- MCP cursor advanced by: {stats.get('discarded_mcp')}",
+                f"- active MCP channel sessions updated: {stats.get('mcp_sessions_updated')}",
+                "New channel events arriving after this point will still be delivered.",
+            ]
+        return [
+            "Ciel Runtime channel backlog status.",
+            f"- chat tail: {stats.get('chat_tail')}",
+            f"- pending LLM items by id range: {stats.get('pending_llm')}",
+            f"- pending MCP items by id range: {stats.get('pending_mcp')}",
+            f"- active MCP channel sessions: {stats.get('mcp_sessions')}",
+        ]
+
+    def handle_channel_clear(self, handler: ShortcutHandler, body: dict[str, Any]) -> bool:
+        if not self.predicates.channel_clear(body):
+            return False
+        value = self.channel.value(body).strip().lower()
+        if value in {"", "all", "clear", "discard", "drop", "purge", "reset", "now"}:
+            lines = self.channel_status_lines(self.channel.clear(), cleared=True)
+        elif value in {"status", "state", "show", "?", "dry-run", "dryrun"}:
+            lines = self.channel_status_lines(self.channel.status(), cleared=False)
+        else:
+            lines = ["Usage: `/channel-clear`, `/channel-clear all`, or `/channel-clear status`."]
+        model, stream = self._model_and_stream(body)
+        self.response.write_anthropic(handler, model, "\n".join(lines), stream)
+        return True
+
+    def handle_live_llm_options(
+        self, handler: ShortcutHandler, body: dict[str, Any]
+    ) -> bool:
+        if not self.predicates.live_llm_options(body):
+            return False
+        value = self.live.llm_value(body)
+        lines, changed = self.live.handle_llm(value)
+        if changed:
+            provider = self.response.current_provider(self.response.load_config())[0]
+            self.response.publish_event(
+                level="info",
+                category="config.llm",
+                message="live LLM options updated from slash command",
+                provider=provider,
+                data={"value": value},
+            )
+        model, stream = self._model_and_stream(body)
+        self.response.write_anthropic(handler, model, "\n".join(lines), stream)
+        return True
+
+    def handle_live_api_keys(
+        self, handler: ShortcutHandler, body: dict[str, Any]
+    ) -> bool:
+        if not self.predicates.live_api_keys(body):
+            return False
+        value = self.live.api_key_value(body)
+        lines, changed = self.live.handle_api_keys(value)
+        if changed:
+            provider, config = self.response.current_provider(self.response.load_config())
+            self.response.publish_event(
+                level="info",
+                category="config.api_key",
+                message="live API key settings updated from slash command",
+                provider=provider,
+                data={"key_count": self.live.api_key_count(provider, config)},
+            )
+        model, stream = self._model_and_stream(body)
+        self.response.write_anthropic(handler, model, "\n".join(lines), stream)
+        return True
+
+
+__all__ = [
+    "ChannelShortcutPorts",
+    "LiveConfigShortcutPorts",
+    "RouterDebugShortcutPorts",
+    "RouterShortcutController",
+    "ShortcutPredicates",
+    "ShortcutResponsePorts",
+]

package/ciel_runtime_support/routing_fallback.py

@@ -0,0 +1,73 @@
+"""Deterministic provider/model fallback planning policies.
+
+The policy decides *what may be tried*; transports remain responsible for
+executing requests.  This separation prevents retry mechanics, credentials,
+and provider wire formats from becoming one stateful conditional block.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Literal
+
+
+FallbackReason = Literal["rate_limit", "unavailable", "timeout", "model_error"]
+DEFAULT_FALLBACK_REASONS: frozenset[FallbackReason] = frozenset(
+    {"rate_limit", "unavailable", "timeout"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RouteTarget:
+    provider: str
+    model: str
+
+    @property
+    def identity(self) -> tuple[str, str]:
+        return (self.provider.strip().lower().replace("_", "-"), self.model.strip())
+
+
+@dataclass(frozen=True, slots=True)
+class FallbackRule:
+    target: RouteTarget
+    reasons: frozenset[FallbackReason] = DEFAULT_FALLBACK_REASONS
+
+
+@dataclass(frozen=True, slots=True)
+class FallbackPlan:
+    primary: RouteTarget
+    rules: tuple[FallbackRule, ...] = ()
+
+    def candidates(self, reason: FallbackReason) -> tuple[RouteTarget, ...]:
+        seen: set[tuple[str, str]] = set()
+        selected: list[RouteTarget] = []
+        for target in (self.primary, *(rule.target for rule in self.rules if reason in rule.reasons)):
+            if not target.provider.strip() or not target.model.strip() or target.identity in seen:
+                continue
+            seen.add(target.identity)
+            selected.append(target)
+        return tuple(selected)
+
+
+def build_fallback_plan(
+    provider: str,
+    model: str,
+    configured: Iterable[dict[str, object]] = (),
+) -> FallbackPlan:
+    """Parse a small configuration surface into an immutable routing plan."""
+
+    rules: list[FallbackRule] = []
+    valid_reasons = {"rate_limit", "unavailable", "timeout", "model_error"}
+    for item in configured:
+        target_provider = str(item.get("provider") or provider).strip()
+        target_model = str(item.get("model") or "").strip()
+        raw_reasons = item.get("reasons")
+        values = raw_reasons if isinstance(raw_reasons, (list, tuple, set, frozenset)) else ()
+        reasons = frozenset(str(value) for value in values if str(value) in valid_reasons)
+        rules.append(
+            FallbackRule(
+                RouteTarget(target_provider, target_model),
+                reasons=reasons or DEFAULT_FALLBACK_REASONS,
+            )
+        )
+    return FallbackPlan(RouteTarget(provider, model), tuple(rules))

package/ciel_runtime_support/runtime_activity_repository.py

@@ -0,0 +1,143 @@
+"""Atomic repository for router and context activity snapshots."""
+
+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 RuntimeActivityPaths:
+    router: Path
+    context_compact: Path
+    context_usage: Path
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeActivityClock:
+    epoch: Callable[[], float]
+    display: Callable[[], str]
+    temporary_suffix: Callable[[], str]
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeActivityEffects:
+    publish: Callable[..., Any]
+    log: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeActivityRepository:
+    paths: RuntimeActivityPaths
+    clock: RuntimeActivityClock
+    effects: RuntimeActivityEffects
+
+    def router_activity(
+        self,
+        event: str,
+        provider: str,
+        model: str | None = None,
+        **fields: Any,
+    ) -> None:
+        try:
+            level = "error" if event == "error" else ("warn" if event in {"retry", "wait"} else "info")
+            self.effects.publish(
+                level=level,
+                category=f"router.{event}",
+                message=f"{event} {provider} {model or ''}".strip(),
+                provider=provider,
+                model=model,
+                data=fields,
+            )
+            self._write(
+                self.paths.router,
+                {"event": event, "provider": provider, "model": model or "", **fields},
+            )
+        except Exception as exc:
+            self._report_failure("router", exc)
+
+    def context_compact(
+        self,
+        provider: str,
+        model: str | None = None,
+        **fields: Any,
+    ) -> None:
+        try:
+            self._write(
+                self.paths.context_compact,
+                {"event": "compact", "provider": provider, "model": model or "", **fields},
+            )
+            self.effects.publish(
+                level="info",
+                category="context.compact",
+                message=f"compact {provider} {model or ''}".strip(),
+                provider=provider,
+                model=model,
+                data=fields,
+            )
+        except Exception as exc:
+            self._report_failure("context_compact", exc)
+
+    def context_usage(
+        self,
+        provider: str,
+        provider_config: dict[str, Any],
+        body: dict[str, Any],
+        source: str,
+        *,
+        estimate_tokens: Callable[[dict[str, Any]], int],
+        context_limit: Callable[[str, dict[str, Any]], int | None],
+    ) -> None:
+        try:
+            tokens = estimate_tokens(body)
+            limit = context_limit(provider, provider_config)
+            percent = round((tokens / limit) * 100.0, 1) if limit else None
+            model = str(body.get("model") or provider_config.get("current_model") or "")
+            details = {
+                "source": source,
+                "tokens": tokens,
+                "context_limit": limit,
+                "percent": percent,
+                "messages": len(body.get("messages") or []),
+                "tools": len(body.get("tools") or []),
+            }
+            self.effects.publish(
+                level="debug",
+                category="context.usage",
+                message=f"context usage {tokens}/{limit or '?'} tokens",
+                provider=provider,
+                model=model,
+                data=details,
+            )
+            self._write(self.paths.context_usage, {"provider": provider, "model": model, **details})
+        except Exception as exc:
+            self._report_failure("context_usage", exc)
+
+    def _write(self, path: Path, data: dict[str, Any]) -> None:
+        record = {"updated_at": self.clock.epoch(), "time": self.clock.display(), **data}
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_name(f"{path.name}.{self.clock.temporary_suffix()}.tmp")
+        temporary.write_text(
+            json.dumps(record, ensure_ascii=False, separators=(",", ":")),
+            encoding="utf-8",
+        )
+        temporary.replace(path)
+
+    def _report_failure(self, operation: str, exc: BaseException) -> None:
+        try:
+            self.effects.log(
+                "WARN",
+                f"runtime_activity_{operation}_failed error={type(exc).__name__}: {exc}",
+            )
+        except Exception:
+            return
+
+
+__all__ = [
+    "RuntimeActivityClock",
+    "RuntimeActivityEffects",
+    "RuntimeActivityPaths",
+    "RuntimeActivityRepository",
+]

package/ciel_runtime_support/runtime_adapters.py

@@ -0,0 +1,104 @@
+"""Concrete runtime adapter used while legacy launchers are incrementally decomposed."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Mapping
+
+from .architecture import LaunchSpec, RuntimeAdapter, RuntimeCommand
+from .registry import AdapterRegistry
+
+
+@dataclass(frozen=True)
+class CliRuntimeAdapter(RuntimeAdapter):
+    """Materialize an already-normalized CLI launch through the runtime contract."""
+
+    name: str
+    executable: str
+    environment: Mapping[str, str] = field(default_factory=dict)
+    channel_injection: bool = False
+
+    def find_executable(self) -> Path | None:
+        return Path(self.executable) if self.executable else None
+
+    def build_command(self, spec: LaunchSpec) -> RuntimeCommand:
+        executable = spec.runtime.executable or self.executable
+        if not executable:
+            raise RuntimeError(f"{self.name} runtime executable is unavailable")
+        prefix = spec.runtime.options.get("prefix_args", ())
+        prefix_args = tuple(str(value) for value in prefix) if isinstance(prefix, (list, tuple)) else ()
+        return RuntimeCommand(
+            argv=(str(executable), *prefix_args, *spec.passthrough),
+            env=dict(self.environment),
+            cwd=spec.cwd,
+        )
+
+    def mcp_config_paths(self, spec: LaunchSpec) -> tuple[Path, ...]:
+        return spec.runtime.mcp_config_paths
+
+    def supports_channel_injection(self, spec: LaunchSpec) -> bool:
+        return bool(self.channel_injection and spec.runtime.enable_channels)
+
+
+class ClaudeRuntimeAdapter(CliRuntimeAdapter):
+    def build_command(self, spec: LaunchSpec) -> RuntimeCommand:
+        options = spec.runtime.options
+        argv = [str(spec.runtime.executable or self.executable), "--dangerously-skip-permissions"]
+        if options.get("bypass_permission_mode"):
+            argv.extend(("--permission-mode", "bypassPermissions"))
+        disallowed = str(options.get("disallowed_tools") or "")
+        if disallowed:
+            argv.extend(("--disallowedTools", disallowed))
+        model = str(options.get("model") or "")
+        if model:
+            argv.extend(("--model", model))
+        argv.extend(str(value) for value in options.get("extra_args", ()))
+        if options.get("passthrough_boundary"):
+            argv.append("--")
+        argv.extend(spec.passthrough)
+        return RuntimeCommand(argv=tuple(argv), env=dict(self.environment), cwd=spec.cwd)
+
+
+class CodexRuntimeAdapter(CliRuntimeAdapter):
+    def build_command(self, spec: LaunchSpec) -> RuntimeCommand:
+        options = spec.runtime.options
+        argv = [str(spec.runtime.executable or self.executable)]
+        argv.extend(str(value) for value in options.get("yolo_args", ()))
+        if spec.mode == "native":
+            argv.extend(str(value) for value in options.get("model_args", ()))
+        elif spec.mode == "routed":
+            argv.extend(str(value) for value in options.get("routed_config_args", ()))
+            argv.extend(str(value) for value in options.get("model_args", ()))
+        else:
+            argv.extend(str(value) for value in options.get("router_config_args", ()))
+        if spec.mode != "native":
+            argv.extend(str(value) for value in options.get("model_catalog_args", ()))
+        for key in ("alternate_screen_args", "mcp_args", "model_alias_args"):
+            argv.extend(str(value) for value in options.get(key, ()))
+        argv.extend(spec.passthrough)
+        return RuntimeCommand(argv=tuple(argv), env=dict(self.environment), cwd=spec.cwd)
+
+
+class AgyRuntimeAdapter(CliRuntimeAdapter):
+    def build_command(self, spec: LaunchSpec) -> RuntimeCommand:
+        options = spec.runtime.options
+        argv = [str(spec.runtime.executable or self.executable)]
+        argv.extend(str(value) for value in options.get("dangerous_args", ()))
+        argv.extend(spec.passthrough)
+        return RuntimeCommand(argv=tuple(argv), env=dict(self.environment), cwd=spec.cwd)
+
+
+RUNTIME_ADAPTERS: AdapterRegistry[RuntimeAdapter] = AdapterRegistry()
+RUNTIME_ADAPTERS.register("claude", lambda **kwargs: ClaudeRuntimeAdapter(name="claude", **kwargs))
+RUNTIME_ADAPTERS.register("codex", lambda **kwargs: CodexRuntimeAdapter(name="codex", **kwargs))
+RUNTIME_ADAPTERS.register("agy", lambda **kwargs: AgyRuntimeAdapter(name="agy", **kwargs))
+
+
+__all__ = [
+    "RUNTIME_ADAPTERS",
+    "AgyRuntimeAdapter",
+    "ClaudeRuntimeAdapter",
+    "CliRuntimeAdapter",
+    "CodexRuntimeAdapter",
+]